ajfile.c

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.

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
);

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 3.0.0

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.

Function ajDirNew

Creates a new directory object.

Synopsis

Prototype

AjPDir ajDirNew (
      const AjPStr name
);

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 3.0.0

Function ajDirNewS

Creates a new directory object.

Synopsis

Prototype

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

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 3.0.0

Function ajDirNewSS

Creates a new directory object.

Synopsis

Prototype

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

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 3.0.0

Function ajDiroutNew

Creates a new directory outputobject.

Synopsis

Prototype

AjPDir ajDiroutNew (
      const AjPStr name
);

Input

name:

(Input)

Directory name

Returns

AjPDir:

New directory object.

Description

Creates a new directory outputobject.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajDiroutNewS

Creates a new directory output object.

Synopsis

Prototype

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

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 3.0.0

Function ajDiroutNewSS

Creates a new directory output object.

Synopsis

Prototype

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

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 3.0.0

Function ajDirName

Returns the name of a directory object

Synopsis

Prototype

AjPStr ajDirName (
      const AjPDir thys
);

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 3.0.0

Function ajDirExt

Returns the extension of a directory object

Synopsis

Prototype

AjPStr ajDirExt (
      const AjPDir thys
);

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 3.0.0

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.

Function ajFileNew

Creates a new file object.

Synopsis

Prototype

AjPFile ajFileNew (
      void
);

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 3.0.0

Function ajFileNewInPipe

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

Synopsis

Prototype

AjPFile ajFileNewInPipe (
      const AjPStr name
);

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 3.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
);

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 3.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
);

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 3.0.0

Function ajFileNewInList

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

Synopsis

Prototype

AjPFile ajFileNewInList (
      AjPList list
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.0.0

Function ajFileHasDir

Tests whether a filename includes a directory specification.

Synopsis

Prototype

AjBool ajFileHasDir (
      const AjPStr name
);

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 3.0.0

Function ajFileNewF

Creates a new file object from an open C file.

Synopsis

Prototype

AjPFile ajFileNewF (
      FILE* file
);

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 3.0.0

Outfile Destructors

Destruction is achieved by closing the file.

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

Function ajOutfileClose

Close and free an outfile object.

Synopsis

Prototype

void ajOutfileClose (
      AjPOutfile* pthis
);

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 3.0.0

Function ajOutfileDel

Close and free an outfile object.

Synopsis

Prototype

void ajOutfileDel (
      AjPOutfile* pthis
);

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 3.0.0

Directory Destructors

Destruction is achieved by deleting the object.

Function ajDirDel

Close and free a directory object.

Synopsis

Prototype

void ajDirDel (
      AjPDir* pthis
);

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 3.0.0

Function ajDiroutDel

Close and free a directory object.

Synopsis

Prototype

void ajDiroutDel (
      AjPDir* pthis
);

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 3.0.0

File Destructors

Destruction is achieved by closing the file.

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

Function ajFileClose

Close and free a file object.

Synopsis

Prototype

void ajFileClose (
      AjPFile* pthis
);

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 3.0.0

Function ajFileOutClose

Closes and deletes an output file object.

Synopsis

Prototype

void ajFileOutClose (
      AjPFile* pthis
);

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 3.0.0

File Assignments

These functions overwrite the file provided as the first argument

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
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.0.0

File Modifiers

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

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
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.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
);

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 3.0.0

Function ajFileReopen

Reopens a file with a new name.

Synopsis

Prototype

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

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 3.0.0

Function ajFileReadLine

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

Synopsis

Prototype

AjBool ajFileReadLine (
      AjPFile thys,
      AjPStr* pdest
);

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 3.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
);

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 3.0.0

Function ajFileGetsTrim

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

Synopsis

Prototype

AjBool ajFileGetsTrim (
      AjPFile thys,
      AjPStr* pdest
);

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 3.0.0

Function ajFileGets

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

Synopsis

Prototype

AjBool ajFileGets (
      AjPFile thys,
      AjPStr* pdest
);

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 3.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 3.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
);

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 3.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
);

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 3.0.0

Function ajFileOutHeader

Writes a header record to the output file.

Synopsis

Prototype

void ajFileOutHeader (
      AjPFile thys
);

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 3.0.0

Function ajFileNameShorten

Truncates a filename to a basic file name.

Synopsis

Prototype

AjBool ajFileNameShorten (
      AjPStr* fname
);

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 3.0.0

Function ajFileNameTrim

Truncates a filename to a basic file name.extension

Synopsis

Prototype

AjBool ajFileNameTrim (
      AjPStr* fname
);

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 3.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
);

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 3.0.0

File Operators

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

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
);

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 3.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
);

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 3.0.0

Function ajFileGetwd

Returns the current directory

Synopsis

Prototype

AjBool ajFileGetwd (
      AjPStr* dir
);

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 3.0.0

Function ajFileDirUp

Changes directory name to one level up

Synopsis

Prototype

AjBool ajFileDirUp (
      AjPStr* dir
);

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 3.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
);

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 3.0.0

Function ajFileExit

Prints a summary of file usage with debug calls

Synopsis

Prototype

void ajFileExit (
      void
);

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 3.0.0

Function ajFileTrace

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

Synopsis

Prototype

void ajFileTrace (
      const AjPFile thys
);

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 3.0.0

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.

Function ajOutfileFile

Returns the AjPFile for an AjPOutfile object

Synopsis

Prototype

AjPFile ajOutfileFile (
      const AjPOutfile thys
);

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 3.0.0

Function ajOutfileFp

Returns the C FILE* for an AjPOutfile object

Synopsis

Prototype

FILE* ajOutfileFp (
      const AjPOutfile thys
);

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 3.0.0

Function ajOutfileFormat

Returns the C FILE* for an AjPOutfile object

Synopsis

Prototype

AjPStr ajOutfileFormat (
      const AjPOutfile thys
);

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 3.0.0

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.

Function ajFileBuffSize

Returns the standard record buffer size for a file

Synopsis

Prototype

ajint ajFileBuffSize (
      void
);

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 3.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
);

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 3.0.0

Function ajFileNameS

Synopsis

Prototype

const AjPStr ajFileNameS (
      const AjPFile thys
);

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 3.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
);

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 3.0.0

Function ajFileGetName

Synopsis

Prototype

AjPStr ajFileGetName (
      const AjPFile thys
);

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 3.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
);

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 3.0.0

Function ajFileLength

Returns the length of a file

Synopsis

Prototype

ajlong ajFileLength (
      const AjPStr fname
);

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 3.0.0

Function ajFileTell

Returns the current position in an open file.

Synopsis

Prototype

ajlong ajFileTell (
      const AjPFile thys
);

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 3.0.0

Function ajFileStdout

Tests whether a file object is really stdout.

Synopsis

Prototype

AjBool ajFileStdout (
      const AjPFile file
);

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 3.0.0

Function ajFileStderr

Tests whether a file object is really stderr.

Synopsis

Prototype

AjBool ajFileStderr (
      const AjPFile file
);

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 3.0.0

Function ajFileStdin

Tests whether a file object is really stdin.

Synopsis

Prototype

AjBool ajFileStdin (
      const AjPFile file
);

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 3.0.0

Function ajFileFp

Returns the C file pointer for an open file.

Synopsis

Prototype

FILE* ajFileFp (
      const AjPFile thys
);

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 3.0.0

Function ajFileEof

Tests whether we have reached end of file already

Synopsis

Prototype

AjBool ajFileEof (
      const AjPFile thys
);

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 3.0.0

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.

Function ajFileBuffNewIn

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

Synopsis

Prototype

AjPFileBuff ajFileBuffNewIn (
      const AjPStr name
);

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 3.0.0

Function ajFileBuffNew

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

Synopsis

Prototype

AjPFileBuff ajFileBuffNew (
      void
);

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 3.0.0

Function ajFileBuffNewFile

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

Synopsis

Prototype

AjPFileBuff ajFileBuffNewFile (
      AjPFile file
);

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 3.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
);

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 3.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
);

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 3.0.0

Function ajFileBuffNewF

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

Synopsis

Prototype

AjPFileBuff ajFileBuffNewF (
      FILE* fp
);

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 3.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
);

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 3.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
);

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 3.0.0

Function ajFileBuffNewDC

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

Synopsis

Prototype

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

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 3.0.0

Function ajFileBuffNewDF

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

Synopsis

Prototype

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

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 3.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
);

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 3.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 3.0.0

Function ajFileNewDF

Opens directory "dir" Looks for file "file"

Synopsis

Prototype

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

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 3.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
);

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 3.0.0

Function ajFileNewDC

Opens directory "dir" Looks for file "file"

Synopsis

Prototype

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

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 3.0.0

Function ajFileBuffNewInList

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

Synopsis

Prototype

AjPFileBuff ajFileBuffNewInList (
      AjPList list
);

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 3.0.0

Buffered File Destructors

Destruction is achieved by closing the file.

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

Function ajFileBuffDel

Destructor for a buffered file object.

Synopsis

Prototype

void ajFileBuffDel (
      AjPFileBuff* pthis
);

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 3.0.0

BufferedFile Modifiers

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

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
);

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 3.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
);

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

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffGetStoreL

Synopsis

Prototype

AjBool ajFileBuffGetStoreL (
      AjPFileBuff thys,
      AjPStr* pdest,
      ajlong* fpos,
      AjBool store,
      AjPStr* astr
);

Input

store:

(Input)

append if true

Output

pdest:	(Output)	Buffer to hold results.
fpos:	(Output)	File position before the read.
astr:	(Output)	string to append to

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 3.0.0

Function ajFileBuffGetL

Synopsis

Prototype

AjBool ajFileBuffGetL (
      AjPFileBuff thys,
      AjPStr* pdest,
      ajlong* fpos
);

Output

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

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 3.0.0

Function ajFileBuffStripHtml

Processes data in the file buffer, removing HTML tokens between angle brackets, plus any TITLE. This seems to be enough to make HTML output readable.

Synopsis

Prototype

void ajFileBuffStripHtml (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

Buffered file with data loaded in the buffer.

Returns

void:

No return value

Description

Processes data in the file buffer, removing HTML tokens between angle brackets, plus any TITLE. This seems to be enough to make HTML output readable.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffLoadC

Adds a line to the buffer.

Intended for cases where the file data must be preprocessed before being seen by the sequence reading routines. The first case was for stripping HTML tags after reading via HTTP.

Synopsis

Prototype

void ajFileBuffLoadC (
      AjPFileBuff thys,
      const char* line
);

Input

line:

(Input)

Line of input.

Input & Output

thys:

(Modify)

Buffered file.

Returns

void:

No return value

Description

Adds a line to the buffer.

Intended for cases where the file data must be preprocessed before being seen by the sequence reading routines. The first case was for stripping HTML tags after reading via HTTP.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffLoadS

Adds a copy of a line to the buffer.

Intended for cases where the file data must be preprocessed before being seen by the sequence reading routines. The first case was for stripping HTML tags after reading via HTTP.

Synopsis

Prototype

void ajFileBuffLoadS (
      AjPFileBuff thys,
      const AjPStr line
);

Input

line:

(Input)

Line of input.

Input & Output

thys:

(Modify)

Buffered file.

Returns

void:

No return value

Description

Adds a copy of a line to the buffer.

Intended for cases where the file data must be preprocessed before being seen by the sequence reading routines. The first case was for stripping HTML tags after reading via HTTP.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffEof

Tests whether we have reached end of file already

Synopsis

Prototype

AjBool ajFileBuffEof (
      const AjPFileBuff thys
);

Input

thys:

(Input)

File buffer

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 3.0.0

Function ajFileBuffEnd

Tests whether the file is exhausted. This means end of file is reached and the buffer is empty

Synopsis

Prototype

AjBool ajFileBuffEnd (
      const AjPFileBuff thys
);

Input

thys:

(Input)

File buffer

Returns

AjBool:

ajTrue if we already set end-of-file

Description

Tests whether the file is exhausted. This means end of file is reached and the buffer is empty

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffReset

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line.

Synopsis

Prototype

void ajFileBuffReset (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffResetStore

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line.

Synopsis

Prototype

void ajFileBuffResetStore (
      AjPFileBuff thys,
      AjBool store,
      AjPStr* astr
);

Input

store:

(Input)

append if true

Output

astr:

(Output)

string to append to

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffResetPos

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line.

Also resets the file position to the last known read, to undo the damage done by (for example) ajseqabi functions.

Synopsis

Prototype

void ajFileBuffResetPos (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line.

Also resets the file position to the last known read, to undo the damage done by (for example) ajseqabi functions.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffFix

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line. Fixes buffer size after the buffer has been edited.

Synopsis

Prototype

void ajFileBuffFix (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Resets the pointer and current record of a file buffer so the next read starts at the first buffered line. Fixes buffer size after the buffer has been edited.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffFreeClear

Deletes freed lines from a file buffer. The free list is used to avoid reallocating space for new records and must be deleted as part of the destructor.

Synopsis

Prototype

void ajFileBuffFreeClear (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Deletes freed lines from a file buffer. The free list is used to avoid reallocating space for new records and must be deleted as part of the destructor.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffClear

Deletes processed lines from a file buffer. The buffer has a record (Pos) of the next unprocessed line in the buffer.

Unbuffered files need special handling. The buffer can be turned off while it still contains data. If so, we have to carefully run it down. If this runs it to zero, we may want to save the last line read.

Synopsis

Prototype

void ajFileBuffClear (
      AjPFileBuff thys,
      ajint lines
);

Input

lines:

(Input)

Number of lines to retain. -1 deletes everything.

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Deletes processed lines from a file buffer. The buffer has a record (Pos) of the next unprocessed line in the buffer.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffClearStore

Deletes processed lines from a file buffer. The buffer has a record (Pos) of the next unprocessed line in the buffer.

Synopsis

Prototype

void ajFileBuffClearStore (
      AjPFileBuff thys,
      ajint lines,
      const AjPStr rdline,
      AjBool store,
      AjPStr* astr
);

Input

lines:	(Input)	Number of lines to retain. -1 deletes everything.
rdline:	(Input)	Last line of input. Used to count characters to be saved
store:	(Input)	append if true

Output

astr:

(Output)

string to append to

Input & Output

thys:

(Modify)

File buffer

Returns

void:

No return value

Description

Deletes processed lines from a file buffer. The buffer has a record (Pos) of the next unprocessed line in the buffer.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffNobuff

Sets file to be unbuffered. If it already has buffered data, we have to first run down the buffer.

Synopsis

Prototype

AjBool ajFileBuffNobuff (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

Buffered file object.

Returns

AjBool:

ajTrue if the file was unbuffered before

Description

Sets file to be unbuffered. If it already has buffered data, we have to first run down the buffer.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffBuff

Sets file to be buffered. If it already has buffered data, we have to first run down the buffer.

Synopsis

Prototype

AjBool ajFileBuffBuff (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

Buffered file object.

Returns

AjBool:

ajTrue if the file was unbuffered before

Description

Sets file to be buffered. If it already has buffered data, we have to first run down the buffer.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Buffered File Operators

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

Function ajFileBuffEmpty

Tests whether a file buffer is empty.

Synopsis

Prototype

AjBool ajFileBuffEmpty (
      const AjPFileBuff thys
);

Input

thys:

(Input)

Buffered file.

Returns

AjBool:

ajTrue if the buffer is empty.

Description

Tests whether a file buffer is empty.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffTrace

Writes debug messages to indicate the contents of a buffered file.

Synopsis

Prototype

void ajFileBuffTrace (
      const AjPFileBuff thys
);

Input

thys:

(Input)

Buffered file.

Returns

void:

No return value

Description

Writes debug messages to indicate the contents of a buffered file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffTraceFull

Writes debug messages to show the full contents of a buffered file.

Synopsis

Prototype

void ajFileBuffTraceFull (
      const AjPFileBuff thys,
      size_t nlines,
      size_t nfree
);

Input

thys:	(Input)	Buffered file.
nlines:	(Input)	Maximum number of lines to trace.
nfree:	(Input)	Maximum number of free lines to trace.

Returns

void:

No return value

Description

Writes debug messages to show the full contents of a buffered file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffPrint

Writes the full contents of a buffered file to the debug file

Synopsis

Prototype

void ajFileBuffPrint (
      const AjPFileBuff thys,
      const char* title
);

Input

thys:	(Input)	Buffered file.
title:	(Input)	Report title

Returns

void:

No return value

Description

Writes the full contents of a buffered file to the debug file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Buffered File Casts

Function ajFileBuffIsBuffered

Tests whether an input file is buffered.

Synopsis

Prototype

AjBool ajFileBuffIsBuffered (
      const AjPFileBuff thys
);

Input

thys:

(Input)

Buffered file object.

Returns

AjBool:

ajTrue if the file was unbuffered before

Description

Tests whether an input file is buffered.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffFp

Returns the C file pointer for an open buffered file.

Synopsis

Prototype

FILE* ajFileBuffFp (
      const AjPFileBuff thys
);

Input

thys:

(Input)

Buffered file.

Returns

FILE*:

C file pointer for the file.

Description

Returns the C file pointer for an open buffered file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileBuffFile

Returns the file object from a buffered file object.

Synopsis

Prototype

AjPFile ajFileBuffFile (
      const AjPFileBuff thys
);

Input

thys:

(Input)

Buffered file.

Returns

AjPFile:

File object.

Description

Returns the file object from a buffered file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Buffered File Inputs

These functions read the contents of a buffered file object

Function ajFileBuffLoad

Reads all input lines from a file into the buffer.

Intended for cases where the file data must be preprocessed before being seen by the sequence reading routines. The first case was for stripping HTML tagsafter reading via HTTP.

Synopsis

Prototype

void ajFileBuffLoad (
      AjPFileBuff thys
);

Input & Output

thys:

(Modify)

Buffered file.

Returns

void:

No return value

Description

Reads all input lines from a file into the buffer.

Intended for cases where the file data must be preprocessed before being seen by the sequence reading routines. The first case was for stripping HTML tagsafter reading via HTTP.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileNameDir

Sets the directory part of a filename

Synopsis

Prototype

AjBool ajFileNameDir (
      AjPStr* filename,
      const AjPDir dir,
      const AjPStr name
);

Input

dir:	(Input)	Directory
name:	(Input)	Base filename

Input & Output

filename:

(Modify)

Filename.

Returns

AjBool:

ajTrue if the replacement succeeded.

Description

Sets the directory part of a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileNameDirSet

Sets the directory part of a filename

Synopsis

Prototype

AjBool ajFileNameDirSet (
      AjPStr* filename,
      const AjPStr dir
);

Input

dir:

(Input)

New directory

Input & Output

filename:

(Modify)

Filename.

Returns

AjBool:

ajTrue if the replacement succeeded.

Description

Sets the directory part of a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileNameDirSetC

Sets the directory part of a filename

Synopsis

Prototype

AjBool ajFileNameDirSetC (
      AjPStr* filename,
      const char* dir
);

Input

dir:

(Input)

Input & Output

filename:

(Modify)

Filename.

Returns

AjBool:

ajTrue if the replacement succeeded.

Description

Sets the directory part of a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileNameExt

Replaces the extension part of a filename

Synopsis

Prototype

AjBool ajFileNameExt (
      AjPStr* filename,
      const AjPStr extension
);

Input

extension:

(Input)

New file extension

Input & Output

filename:

(Modify)

Filename.

Returns

AjBool:

ajTrue if the replacement succeeded.

Description

Replaces the extension part of a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileNameExtC

Replaces the extension part of a filename

Synopsis

Prototype

AjBool ajFileNameExtC (
      AjPStr* filename,
      const char* extension
);

Input

extension:

(Input)

New file extension

Input & Output

filename:

(Modify)

Filename.

Returns

AjBool:

ajTrue if the replacement succeeded.

Description

Replaces the extension part of a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileScan

Recursively scan through a directory

Synopsis

Prototype

ajint ajFileScan (
      const AjPStr path,
      const AjPStr filename,
      AjPList* result,
      AjBool show,
      AjBool dolist,
      AjPList* list,
      AjPList rlist,
      AjBool recurs,
      AjPFile outf
);

Input

path:	(Input)	Directory to scan
filename:	(Input)	Filename to search for (or NULL)
show:	(Input)	Print all files found if set
dolist:	(Input)	Store all filenames in a list (if set)
recurs:	(Input)	Do recursion

Output

result:	(Output)	List for matching filenames
list:	(Output)	List for dolist results

Input & Output

rlist:	(Modify)	List of directories to ignore
outf:	(Modify)	File for "show" results (or NULL)

Returns

ajint:

number of entries in list

Description

Recursively scan through a directory

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileTestSkip

Tests a filename against wildcard lists of file names to be included and excluded.

By default files are included. The exclusion list is used to trim out files, and the inclusion list is then used to add selected files again.

Synopsis

Prototype

AjBool ajFileTestSkip (
      const AjPStr fullname,
      const AjPStr exc,
      const AjPStr inc,
      AjBool keep,
      AjBool ignoredirectory
);

Input

fullname:	(Input)	File to test
exc:	(Input)	List of wildcard names to exclude
inc:	(Input)	List of wildcard names to include
keep:	(Input)	Default to keep if ajTrue, else skip unless inc is matched.
ignoredirectory:	(Input)	Delete directory from name before testing.

Returns

AjBool:

ajTrue if the filename is accepted.

Description

Tests a filename against wildcard lists of file names to be included and excluded.

By default files are included. The exclusion list is used to trim out files, and the inclusion list is then used to add selected files again.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileDirTrim

Trims the directory path (if any) from a filename

Synopsis

Prototype

AjBool ajFileDirTrim (
      AjPStr* name
);

Input & Output

name:

(Modify)

Filename

Returns

AjBool:

ajTrue is there was a directory

Description

Trims the directory path (if any) from a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileExtnTrim

Trims the extension (if any) from a filename

Synopsis

Prototype

AjBool ajFileExtnTrim (
      AjPStr* name
);

Input & Output

name:

(Modify)

Filename

Returns

AjBool:

ajTrue is there was an extension

Description

Trims the extension (if any) from a filename

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileDirExtnTrim

Trims the directory path (if any) and extension (if any) from a filename.

Synopsis

Prototype

AjBool ajFileDirExtnTrim (
      AjPStr* name
);

Input & Output

name:

(Modify)

Filename

Returns

AjBool:

ajTrue is there was a directory path or extension.

Description

Trims the directory path (if any) and extension (if any) from a filename.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileTempName

Returns an available temporary filename that can be opened for writing Filename will be of the form progname-time.randomnumber Tries 5 times to find a new filename. Returns NULL if not successful or the file cannot be opened for writing. This function returns only the filename, not a file pointer.

Synopsis

Prototype

const char* ajFileTempName (
      const char* dir
);

Input

dir:

(Input)

Directory for filename or NULL for current dir (.)

Returns

const char*:

available filename or NULL if error.

Description

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileWriteByte

Writes a single byte to a binary file

Synopsis

Prototype

ajint ajFileWriteByte (
      AjPFile thys,
      char ch
);

Input

ch:

(Input)

Character

Input & Output

thys:

(Modify)

Output file

Returns

ajint:

Return value from fwrite

Description

Writes a single byte to a binary file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 3.0.0

Function ajFileWriteChar

Writes a text string to a binary file

Synopsis

Prototype

ajint ajFileWriteChar (
      AjPFile thys,
      const char* str,
      ajint len
);

Input

str:	(Input)	Text string
len:	(Input)	Length (padded) to use in the file

Input & Output

thys:

(Modify)

Output file

Returns

ajint:

Return value from fwrite

Description

Writes a text string to a binary file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

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