2.2.2 - Utility Methods - JdlUtils

John W. Campbell

2.2.2.1 Introduction

This class provides a series of utility methods which were developed for use with the Jdl package of objects. They comprise methods which are considered to be of general use beyond the context for which they were originally developed. They are classified under a number of section headings.

Class, fields and methods:

Class Details
Accessible Fields
String Utilities
File Name Utilities
Copy a File
Character Widths
Indexing Arrays
Window Utilities
Preparing Text for Output
Integer Ranges
XML String Utilities
Manipulating Numbers
Date Utility
Millimetres, Inches and Points
Colour Methods
Opening & Reading Files
Fit a Circle
Matrix and Vector Methods
Byte Manipulation

2.2.2.2 Class Details

Package:: Jdl.JdlLib;
Class name:: JdlUtils
Class definition:: public class JdlUtils
Extends:: Object
Implements:: none
Actions:: none

2.2.2.3 Accessible Fields

The following accessible fields have been defined:

public final static int SOLID_FRAME: JdlFrame type option: solid.
public final static int RAISED_FRAME: JdlFrame type option: raised.
public final static int INSET_FRAME: JdlFrame type option: inset.
public final static int ETCHED_OUT_FRAME: JdlFrame type option: etched out.
public final static int ETCHED_IN_FRAME: JdlFrame type option: etched in.

2.2.2.4 String Utilities

2.2.2.4.1 Introduction

This section contains methods acting on strings to test for blank strings, to trim a string in various ways and to set up a blank string.

Methods:

Test blank/null string - blankString
Chop trailing blanks - chopBlanks
Trim and quote - trimAndQuote
Trim and unquote - trimAndUnquote
Set blank string - setBlankString
Set zeroes string - setZeroesString
Pad string left - padStringLeft
Pad string left with zeroes - padStringZeroesLeft
Pad string right - padStringRight
Pad string right with zeroes - padStringZeroesRight

2.2.2.4.2 Test blank/null string - blankString

This method tests for a null or blank String. The three cases, of a null String, a zero length String or a String containing only blank (space) characters, all return a true value from the method. This method is used extensively in the Jdl package.

Method Definition:

public static boolean blankString(String str)

Parameters List:

str: The string to be tested.

Method Return:

True if null/blank, otherwise false.

2.2.2.4.3 Chop trailing blanks - chopBlanks

This method chops trailing blanks from the end of a string.

Method Definition:

public static String chopBlanks(String str)

Parameters List:

str: The string from which trailing blanks are to be removed.

Method Return:

Returns the chopped string.

2.2.2.4.4 Trim and quote - trimAndQuote

This method trims a string (String .trim() method) and adds enclosing quotes if these are not already present.

Method Definition:

public static String trimAndQuote(String str)

Parameters List:

str: The string to be processed.

Method Return:

The trimmed and quoted string.

2.2.2.4.5 Trim and unquote - trimAndUnquote

This method trims a string and removes any enclosing quotes if present.

Method Definition:

public static String trimAndUnquote(String str)

Parameters List:

str: The string to be processed.

Method Return:

The trimmed and unquoted string.

2.2.2.4.6 Set blank string - setBlankString

This method sets up a blank string with a given number of blank (space) characters.

Method Definition:

public static String setBlankString(int n)

Parameters List:

n: The number of blank characters required.

Method Return:

The required blank string.

2.2.2.4.7 Set zeroes string - setZeroesString

This method sets up a string with a given number of zero characters.

Method Definition:

public static String setZeroesString(int n)

Parameters List:

n: The number of zero characters required.

Method Return:

The required string of zeroes.

2.2.2.4.8 Pad string left - padStringLeft

This method left-pads a string with blank characters to a requested width if it is shorter than that width.

Method Definition:

public String padStringLeft(String str, int w)

Parameters List:

str: The string to pad.
w: The required width.

Method Return:

The padded string.

2.2.2.4.9 Pad string left with zeroes - padStringZeroesLeft

This method left-pads a string with zero characters to a requested width if it is shorter than that width.

Method Definition:

public String padStringZeroesLeft(String str, int w)

Parameters List:

str: The string to pad.
w: The required width.

Method Return:

The padded string.

2.2.2.4.10 Pad string right - padStringRight

This method right-pads a string with blank characters to a requested width if it is shorter than that width.

Method Definition:

public String padStringRight(String str, int w)

Parameters List:

str: The string to pad.
w: The required width.

Method Return:

The padded string.

2.2.2.4.11 Pad string right with zeroes - padStringZeroesRight

This method right-pads a string with zero characters to a requested width if it is shorter than that width.

Method Definition:

public String padStringZeroesRight(String str, int w)

Parameters List:

str: The string to pad.
w: The required width.

Method Return:

The padded string.

2.2.2.5 File Name Utilities

2.2.2.5.1 Introduction

This section includes methods to extract the name part from a file name, manipulate file extensions, modify file name separators, and find the home directory.

Methods:

Get name from filename - nameOfFile
Get file extension - fileExtension
Change file extension - changeFileExtension
Compose file name - composeFileName
Replace filename separators - currentSepFilename
File name from template - filenameFromTemplate
Get home directory - homeDirectory

2.2.2.5.2 Get name from filename - nameOfFile

This method gets the name part of a filename and optionally add a new file extension to this name.

Method Definition:

public static String nameOfFile(String filename, String new_ext)

Parameters List:

filename: The name of the file to be processed.
new_ext: A new extension to be added to the extracted name part of the file. Set to null if not required.

Method Return:

The name part of the file name (optionally with a new extension).

2.2.2.5.3 Get file extension - fileExtension

This method extracts the file extension from a file name.

Method Definition:

public static String fileExtension(String filename)

Parameters List:

filename: The name of the file to be processed.

Method Return:

Returns the file extension (null if none).

2.2.2.5.4 Change file extension - changeFileExtension

This method replaces the current file name extension with a new file name extension.

Method Definition:

public static String changeFileExtension (String filename, String ext)

Parameters List:

filename: The name of the file to be processed.
ext: The new file name extension.

Method Return:

Returns the filename with the changed extension.

2.2.2.5.5 Compose file name - composeFileName

This method composes a file name from a directory name and file name and optionally replaces the filename separators with those appropriate to the current system.

Method Definition:

public static String composeFileName (String dir, String name)

Parameters List:

dir: Directory (or folder) name
name: File name (relative to directory) with extension

Method Return:

Returns the completed file name

2.2.2.5.6 Replace filename separators - currentSepFilename

This method replaces the filename separators with those which are appropriate for current the current system. The input string may have '/' or '\' characters as separators.

Method Definition:

public static String currentSepFilename(String filnam)

Parameters List:

filnam: The input file name.

Method Return:

Returns the processed filename.

2.2.2.5.7 File name from template - filenameFromTemplate

This method returns a file name from a template string containing a hash field and an integer which is to replace that field. The added integer will be padded to the left with zeroes if necessary so that it occupies the number of characters given in the template's hash field. If the integer string is longer than this, then it will be just replace the hash field. e.g. template = lys###.image would give lys001.image, lys025.image or lys1321.image for numbers 1, 25 or 1321. This is the intended mode of use. If there is no hash field in the template but there is a file extension, the number will be inserted just prior to the dot before the extension e.g. for a template lys.image and number 25 the file name would be lys25.image. If there is no hash and no file extension the number will be appended to the template string. If there is more than one hash string, then the last one found will be used.

Method Definition:

public static String filenameFromTemplate (String template, int num)

Parameters List:

template: The file name template string, normally with a hash field.
num: The number to insert in the string as described above.

Method Return:

The file name string formed from the template and the number.

2.2.2.5.8 Get home directory - homeDirectory

Gets the home directory with a final filename separator character added. The method requires access to system properties and the security permissions will need to be set appropriately if the information is to be accessed from an applet.

Method Definition:: public static String homeDirectory()
Parameters List:: none
Method Return:: The home directory path (null if access not accessible)

2.2.2.6 Copy a File

2.2.2.6.1 Introduction

This section contains a pair of methods to copy a file. The difference lies in the way the input and output files are specified.

Methods:

Copy a file - copyFile
Copy a file - copyFile

2.2.2.6.2 Copy a file - copyFile

This method copies a file from an input file to an output file. The input and output files are specified by their file names.

Method Definition:

public static boolean copyFile(String filnam1, String filnam2)

Parameters List:

filnam1: Input file name
filnam2: Output file name

Method Return:

Error flag = true if error, =false if copy OK

2.2.2.6.3 Copy a file - copyFile

This method copies a file from an input file to an output file. The input and output files are specified as File objects.

Method Definition:

public static boolean copyFile(File file1, File file2)

Parameters List:

file1: The input file.
file2: The output file.

Method Return:

Error flag = true if error, =false if copy OK.

2.2.2.7 Character Widths

2.2.2.7.1 Introduction

This section has methods for finding the maximum character width for a font for ASCII or digit characters and for calculating an average character width based on a typical character string.

Methods:

Maximum ascii character width - maxAsciiCharWidth
Maximum digit character width - maxDigitCharWidth
Equivalent columns - equivalentColumns

2.2.2.7.2 Maximum ascii character width - maxAsciiCharWidth

Returns the maximum width of an ASCII character (from a space through to a tilde and pound sign) for a given font.

Method Definition:

public static int maxAsciiCharWidth (Font font, Component c)

Parameters List:

font: The font to be examined.
c: A window component for the screen on which the characters are to be displayed.

Method Return:

Returns the maximum width in pixels.

2.2.2.7.3 Maximum digit character width - maxDigitCharWidth

Returns the maximum width of a decimal digit character (0-9) for a given font.

Method Definition:

public static int maxDigitCharWidth (Font font, Component c)

Parameters List:

font: The font to be examined.
c: A window component for the screen on which the characters are to be displayed.

Method Return:

Returns the maximum width in pixels.

2.2.2.7.4 Equivalent columns - equivalentColumns

Returns the number of 'm' width columns for a given number of columns based on a typical string (rounded up). (The width of 'm' is used in some Java methods as the 'standard' character when widths are specified in columns of characters)

Method Definition:

public static int equivalentColumns (int cols, String typical, Font font, Component c)

Parameters List:

cols: The number of columns required of typical text.
typical: A typical text string.
font: The font to be used.
c: The component on which the text is to be rendered.

Method Return:

Returns the equivalent number of 'm' width columns.

2.2.2.8 Indexing Arrays

2.2.2.8.1 Introduction

This section has methods to index vectors of integer or real numbers.

Methods:

Index integer array - indexIntegerArray
Index double array - indexDoubleArray
Index float array - indexFloatArray

2.2.2.8.2 Index integer array - indexIntegerArray

This method will index a vector of integers in ascending order of magnitude. The sort is stabilised to preserve the order of equal values.

Method Definition:

public static void indexIntegerArray(int[] iv, int n, int[] indx)

Parameters List:

iv: The array of integer values to be indexed.
n: The number of values in the array.
indx: An array in which the integer vector of indices is returned ('n' values).

2.2.2.8.3 Index double array - indexDoubleArray

This method will index a vector of doubles in ascending order of magnitude. The sort is stabilised to preserve the order of equal values.

Method Definition:

public static void indexDoubleArray(double[] dv, int n, int[] indx)

Parameters List:

dv: The array of doubles values to be indexed.
n: The number of values in the array.
indx: An array in which the integer vector of indices is returned ('n' values).

2.2.2.8.4 Index float array - indexFloatArray

This method will index a vector of floats in ascending order of magnitude. The sort is stabilised to preserve the order of equal values.

Method Definition:

public static void indexFloatArray(float[] fv, int n, int[] indx)

Parameters List:

fv: The array of floats values to be indexed.
n: The number of values in the array.
indx: An array in which the integer vector of indices is returned ('n' values).

2.2.2.9 Window Utilities

2.2.2.9.1 Introduction

This section has methods to find the owning frame of a window, to set the position of a dialogue window relative to a given component window and to draw a window frame.

Methods:

Get owning frame - owningFrame
Set dialogue position - setDialogLocation
Draw a window frame - drawFrame
Custom cursor - customCursor
Get mouse button number - mouseButtonNumber

2.2.2.9.2 Get owning frame - owningFrame

This method finds the owing frame of a given Java Component object.

Method Definition:

public static Frame owningFrame (Component component)

Parameters List:

component: The Component object for which the owning frame is to be found.

Method Return:

Returns the owning Frame object (null if none found).

2.2.2.9.3 Set dialogue position - setDialogLocation

This method sets the position of a dialogue window relative to a given Java Component object.

Method Definition:

public static void setDialogLocation (Dialog d, Component c, int x, int y)

Parameters List:

d: The Dialog window object.
c: The Component object with respect to which the dialogue is to be positioned.
x: The required 'x' position of the dialogue with respect to the component.
y: The required 'y' position of the dialogue with respect to the component.

2.2.2.9.4 Draw a window frame - drawFrame

This method draws a three dimensional frame on a window.

Method Definition:

public static void drawFrame (Graphics g, int type, int xo, int yo, int w, int h, int thickness, Color bright, Color dark, Color solid)

Parameters List:

g: The Graphics object for the drawing.
type: The frame type:
= 0, solid - SOLID_FRAME
= 1, raised - RAISED_FRAME
= 2, inset - INSET_FRAME
= 3, etched out - ETCHED_OUT_FRAME
= 4, etched in - ETCHED_IN_FRAME
xo: The 'x' origin for the frame.
yo: The 'y' origin for the frame.
w: The width for the frame in pixels.
h: The height for the frame in pixels.
thickness: The frame thickness in pixels (best if even for etched frames).
bright: Colour for the highlighted edges.
dark: Colour for the shaded edges.
solid: Colour for a solid border.

2.2.2.9.5 Custom cursor - customCursor

This method is used to create a custom cursor from a 16x16 and 32x32 image. It sets the best custom cursor given a 16*16 and a 32*32 cursor image. If both equally good fits, the 32*32 image is chosen.

Method Definition:

public static Cursor customCursor (Image img16, Image img32, Toolkit tk, boolean cent, String name)

Parameters List:

im16: The 16x16 image.
img32: The 32x32 image.
tk: The Toolkit object.
cent: If true the cursor 'hotspot' will be at the centre (7, 7) or (15, 15) for a 16x16 or 32x32 cursor size respectively; if false it will be at the top left corner (0, 0).
name: A name for the cursor.

Method Return:

Returns the custom cursor as a Cursor object.

2.2.2.9.6 Get mouse button number - mouseButtonNumber

This method returns the mouse button number from 1 to 3 given a mouse event.

Method Definition:: public static int mouseButtonNumber(MouseEvent ev)
Parameters List:: none
Method Return:: The mouse button number from 1 to 3; 0 if not recognized.

2.2.2.10 Preparing Text for Output

2.2.2.10.1 Introduction

This section has methods for preparing and formatting output lines for sections of text which use fixed width characters.

Methods:

Format paragraph - textOutputStrings
Position pre-formatted text - preformOutputStrings

2.2.2.10.2 Format paragraph - textOutputStrings

Converts a paragraph of text to a set of formatted (fixed character width) output text strings prior to printing or output to a text file. The method allows for the inclusion of a margin and, optionally, a lead string for the first output line. If a lead string is present, subsequent lines will be left justified to the end of that string. The text may be justified to the right as well as the left margin if required.

Method Definition:

public static String[] textOutputStrings(int margw, int ncols, String lead_str, String str, boolean nl_rem, boolean just)

Parameters List:

margw: Left hand margin width as a number of columns.
ncols: Number of printing columns (after margin).
lead_str: Lead string for the first output line; other lines will be inset by the width of this string (in addition to margin). May be null if not required.
str: The string containing the text to be output.
nl_rem: If true, newlines in the string will be ignored. If false, the formatting will only apply to the sections of text between the newline characters.
just: If true, right justify the text (as well as left justify) The last line will not be right justified.

Method Return:

Returns an array of strings ready for printing or output to a file.

2.2.2.10.3 Position pre-formatted text - preformOutputStrings

Converts a section of pre-formatted text to a set of output text strings prior to printing or output to a text file. The text is offset from the left by the margin width and, if specified, the width of the lead string but otherwise its formatting is unchanged.

Method Definition:

public static String[] preformOutputStrings(int margw, String lead_str, String str)

Parameters List:

margw: Left hand margin width as a number of columns.
lead_str: Lead string for the first output line; other lines will be inset by the width of this string (in addition to margin). May be null if not required.
str: The string containing the text to be output.

Method Return:

Returns an array of strings ready for printing or output to a file.

2.2.2.11 Integer Ranges

2.2.2.11.1 Introduction

This section has methods for interpreting a string specifying ranges of integer values and for determining whether a given integer lies within these ranges.

Methods:

Get integer ranges - integerRanges
Integer in range - inRange
Ranges string - rangeString

2.2.2.11.2 Get integer ranges - integerRanges

Converts a string to an array of positive integer number ranges. The string is of the form n1, n2-n3, n4 - n5 , n6 , n7 with a mixture of integer lists or integer ranges specified as two integers separated by a minus sign. Each single integer or integer range is separated by space(s) or a comma (with additional spaces allowed). e.g.
2,4, 6, 11-14, 3, 7 - 9, 5
Expanded and sorted, this list would comprise: 2 3 4 6 7 8 9 11 12 13 14.

Method Definition:

public static int[][] integerRanges(String str, JdlError err)

Parameters List:

str: The string containing the integer range specification.
err: An error return object. If an error was found 'err.err' will be set to true, an error message will be returned in 'err.msg1' and the return flag 'err.flag' may have the following values:
= 1, Null/blank string
= 2, Invalid integer syntax
= 3, Negative value not preceded by a positive value

Method Return:

A two dimensional array containing pairs of integers. The first dimension has one index for each pair and the second has a dimension of two for the two numbers in the pair. The number pairs represent start and end values of a number range; for single integers the start and end values will be the same.

2.2.2.11.3 Integer in range - inRange

See if an integer is within a set of integer ranges held in an array. (An array of the required form can be returned from the integerRanges(..) method if its use is appropriate)

Method Definition:

public static boolean inRange(int[][] ranges, int iv)

Parameters List:

ranges: An array int[][2] with pairs of integers defining the min and max values of each range (either order).
iv: The integer value to be tested.

Method Return:

True if within a range, otherwise false.

2.2.2.11.4 Ranges string - rangeString

Prepare a string from an array of integer ranges in the form required by the integerRanges(..) method.

Method Definition:

public static String rangeString(int nrange, int[][] ranges)

Parameters List:

nrange: Number of ranges
ranges: Array int[][2] containing start and end values for each integer of the 'nrange' integer ranges.

Method Return:

The string with the ranges

2.2.2.12 XML String Utilities

2.2.2.12.1 Introduction

This section contains methods to assist with the handling of XML or XHTML data. Methods are included to encode/decode reserved characters, to parse token/element data strings, to read tokens/strings from an XML structured file and to read an XML file into a string with optional substitution of the SYSTEM DTD file name.

Methods:

Remove reserved XML - removeReservedXML
Remove reserved XHTML - removeReservedXHTML
Read next XML token - nextXMLToken
String from XML file - xmlFileToString
Replace escaped characters - replaceReservedXML
Replace non-breaking space - replaceNonBreakingSpace
Get XML element name - getElementName
Get name and type - getElementName
Get XML element type - getElementType

2.2.2.12.2 Remove reserved XML - removeReservedXML

This method removes reserved XML characters from a string and replaces them with the required escape sequences. The reserved characters <, >, &, ' and " are replaced with the escape sequences <, >, &, ' and " respectively.

Method Definition:

public static String removeReservedXML(String str)

Parameters List:

str: The string in which special characters are to be replaced with XML escape sequences.

Method Return:

Returns the altered string.

2.2.2.12.3 Remove reserved XHTML - removeReservedXHTML

This method removes reserved XHTML characters from a string and replaces them with the appropriate escape sequences. Note that this differs from the removeReservedXML(..) method in the treatment of the apostrophe which is replaced with the escape sequence '.

Method Definition:

public static String removeReservedXHTML(String str)

Parameters List:

str: The string in which special characters are to be replaced with XHTML escape sequences.

Method Return:

Returns the altered string.

2.2.2.12.4 Read next XML token - nextXMLToken

This method reads the next token from an XML structured file. If a string is found before a token (a lead string), this will also be returned. Strings and tokens are trimmed.

Method Definition:

public static JdlXMLTokenString nextXMLToken(BufferedReader bsr) throws IOException

Parameters List:

bsr: Buffered reader for the file

Method Return:

Returns a JdlTokenStringXML object with details of the token and any lead string found. Returns null if no more tokens present.

2.2.2.12.5 String from XML file - xmlFileToString

This method reads an XML file and returns it in a string. Fields are trimmed (including newline characters). If a new DTD file name is given, this will replace the filename from the input XML file which follows the SYSTEM keyword in the !DOCTYPE definition.

Method Definition:

public static String xmlFileToString(BufferedReader bsr, String new_dtd) throws IOException

Parameters List:

bsr: Buffered reader for the file
new_dtd: Name of DTD file to replace the DTD file specification following the SYSTEM keyword in the !DOCTYPE definition - ignored if null or blank.

Method Return:

The string containing the XML file contents.

2.2.2.12.6 Replace escaped characters - replaceReservedXML

This method replaces the escaped reserved XML or XHTML characters in a string with the original characters. It also enables non-breaking space characters to be replaced by ordinary space characters for by a user selected 'placeholder' character or string.

Method Definition:

public static String replaceReservedXML(String str, String nbs)

Parameters List:

str: The string in which XML or XHTML escaped characters are to be reinstated.
nbs: Replace any non-breaking space escapes with this string e.g. " " replace with a normal space, " " leave in place or another 'placeholder' string for further processing at a later stage. The string "\u00FF" may be used and can be replaced in a string prior to printing using the replaceNonBreakingSpace(..) method; This encodes a single character for the space placeholder so that the string may be formatted (e.g. using textOutputStrings(..)) with non-breaking space being preserved.

Method Return:

Returns the altered string.

2.2.2.12.7 Replace non-breaking space - replaceNonBreakingSpace

This method replaces any non-breaking space characters which have been temporarily stored as the placeholder character \u00FF. These characters are replaced by normal space characters.

Method Definition:

public static String replaceNonBreakingSpace (String str)

Parameters List:

str: The string in which non-breaking space characters are represented by the character \u00FF (see replaceReservedXML(..))

Method Return:

The string in which these non-breaking space characters have been replaced by normal space characters.

2.2.2.12.8 Get XML element name - getElementName

This method gets an XML element name from a token string.

Method Definition:

public static String getElementName (String tokstr)

Parameters List:

tokstr: The XML token string with or without enclosing < ... > characters.

Method Return:

The element name.

2.2.2.12.9 Get name and type - getElementName

This method gets an XML element name and its type from a token string.

Method Definition:

public static String getElementName (String tokstr, JdlInt typ)

Parameters List:

tokstr: The XML token string with or without enclosing < ... > characters.
typ: Returns the token type:
= 1, start element
= 2, end element
= 3, empty element
If the string is not enclosed by < ... > then corresponding negative value will be returned.

Method Return:

Returns the element name.

2.2.2.12.10 Get XML element type - getElementType

This method gets the element type (start/end/empty) from an XML token string.

Method Definition:

public static int getElementType (String tokstr)

Parameters List:

tokstr: The XML token string with or without enclosing < ... > characters.

Method Return:

Returns the token type:
= 1, start element
= 2, end element
= 3, empty element
If the string is not enclosed by < ... >, then corresponding negative value will be returned.

2.2.2.13 Manipulating Numbers

2.2.2.13.1 Introduction

This section has methods for finding the nearest integer, finding the highest common factor, manipulating numbers as digits, interpreting strings as numbers and preparing strings from numbers for output.

Methods:

Nearest integer - nint
Nearest integer - nint
Return the number of digits in an integer value. - ndigit
Number of digits - ndigit
I'th digit - ithDigit
Highest common factor - highestCommonFactor
Integer from string - intval
Integer from string - intval
Double from string - dval
Double from string - dval
Integer to string - intstr
Integer to string - intstr
Integer to string - intstrZpad
Float to string - fstr
Float to string - fstr
Double to string - fstr
Double to string - fstr

2.2.2.13.2 Nearest integer - nint

Returns the nearest integer to a float value.

Method Definition:

public static int nint (float x)

Parameters List:

x: The floating point value.

Method Return:

Returns the nearest integer.

2.2.2.13.3 Nearest integer - nint

Returns the nearest integer to a double value.

Method Definition:

public static int nint (double x)

Parameters List:

x: The 'double' value.

Method Return:

Returns the nearest integer.

2.2.2.13.4 Return the number of digits in an integer value. - ndigit

Method Definition:

public static int ndigit(int i)

Parameters List:

i: The 'int' value.

Method Return:

Returns the number of digits.

2.2.2.13.5 Number of digits - ndigit

Returns the number of digits in a long integer value.

Method Definition:

public static int ndigit(long i)

Parameters List:

i: The 'long' value.

Method Return:

Returns the number of digits.

2.2.2.13.6 I'th digit - ithDigit

Returns the i'th digit in an integer value.

Method Definition:

public static int ithDigit(int n, int i)

Parameters List:

n: The integer value.
i: The digit required (from 1 upwards, left to right)

Method Return:

Returns the value of the i'th digit, -1 if out of range.

2.2.2.13.7 Highest common factor - highestCommonFactor

Returns the highest common factor for two integers.

Method Definition:

public static int highestCommonFactor(int ii, int jj)

Parameters List:

ii: The first integer.
jj: The second integer.

Method Return:

The highest common factor.

2.2.2.13.8 Integer from string - intval

This method converts a string representation of an integer to an integer value.

Method Definition:

public static int intval(String str, int errval)

Parameters List:

str: The string to convert.
errval: The value to return if there is an error in the integer syntax

Method Return:

The integer value (will be 'errval' if there was an error in the value)

2.2.2.13.9 Integer from string - intval

This method converts a string representation of an integer to an integer value.

Method Definition:

public static int intval(String str, JdlError err)

Parameters List:

str: The string to convert
err: An error object in which to set error return codes. If an error is found 'err.err' will be set to true, an error message will be returned in 'err.msg1' and the flag 'err.flag' will be set as follows:
= 0, OK
= 1, Null/blank string (or + character only)
= 2, Invalid character in string
= 3, Java conversion exception

Method Return:

The integer value (will be 0 if there was an error in the value)

2.2.2.13.10 Double from string - dval

This method converts a string representation of a double to an double value.

Method Definition:

public static double dval(String str, double errval)

Parameters List:

str: The string to convert.
errval: The value to return if there is an error in the double. syntax.

Method Return:

The double value (will be 'errval' if there was an error in the value).

2.2.2.13.11 Double from string - dval

This method converts a string representation of a double to an double value.

Method Definition:

public static double dval(String str, JdlError err)

Parameters List:

str: The string to convert
err: An error object in which to set error return codes. If an error is found 'err.err' will be set to true, an error message will be returned in 'err.msg1' and the flag 'err.flag' will be set as follows:
= 0, OK
= 1, Null/blank string (or + character only) = 2, Invalid character in string
= 3, Java conversion exception

Method Return:

The double value (will be 0.0 if there was an error in the value).

2.2.2.13.12 Integer to string - intstr

This method converts an integer value to a string.

Method Definition:

public static String intstr(int i)

Parameters List:

i: The integer to be converted.

Method Return:

The string representation of the integer.

2.2.2.13.13 Integer to string - intstr

This method converts an integer value to a string right justified in a requested field width if it is shorter than that field width.

Method Definition:

public static String intstr(int i, int nw)

Parameters List:

i: The integer to be converted.
nw: Field width as a number of characters.

Method Return:

The string representation of the integer.

2.2.2.13.14 Integer to string - intstrZpad

This method converts an integer value to a string right justified in a requested field width if it is shorter than that field width with leading zeroes.

Method Definition:

public static String intstrZpad(int i, int nw)

Parameters List:

i: The integer to be converted.
nw: Field width as a number of characters.

Method Return:

The string representation of the integer.

2.2.2.13.15 Float to string - fstr

This method converts a float value to a string with a requested number of decimal places.

Method Definition:

public static String fstr (float x, int nd)

Parameters List:

x: The 'float' value up to a maximum absolute value of 1.0E18f; larger values will be retured in the Java default format.
nd: The number of decimal places required (up to 18). If negative then the value will be output in scientific format with -nd decimal places.

Method Return:

Returns the required string.

2.2.2.13.16 Float to string - fstr

This method converts a float value to a string with a requested number of decimal places right justified in a requested field width if it is shorter than that field width.

Method Definition:

public static String fstr (float x, int nd, int nw)

Parameters List:

x: The 'double' value up to a maximum absolute value of 1.0E18; larger values will be retured in the Java default format.
nd: The number of decimal places required (up to 18). If negative then the value will be output in scientific format with -nd decimal places.
nw: Field width as a number of characters.

Method Return:

Returns the required string.

2.2.2.13.17 Double to string - fstr

This method converts a double value to a string with a requested number of decimal places.

Method Definition:

public static String fstr (double x, int nd)

Parameters List:

x: The 'double' value up to a maximum absolute value of 1.0E18; larger values will be retured in the Java default format.
nd: The number of decimal places required (up to 18). If negative then the value will be output in scientific format with -nd decimal places.

Method Return:

Returns the required string.

2.2.2.13.18 Double to string - fstr

This method converts a double value to a string with a requested number of decimal places right justified in a requested field width if it is shorter than that field width.

Method Definition:

public static String fstr (double x, int nd, int nw)

Parameters List:

x: The 'double' value up to a maximum absolute value of 1.0E18; larger values will be retured in the Java default format.
nd: The number of decimal places required (up to 18). If negative then the value will be output in scientific format with -nd decimal places.
nw: Field width as a number of characters.

Method Return:

Returns the required string.

2.2.2.14 Date Utility

2.2.2.14.1 Introduction

This section has a single method to return the current date in a 'standard' form.

Method:

Get date string - standardDate

2.2.2.14.2 Get date string - standardDate

Returns the current date as a string in a 'standard' form e.g. 25 July 2003.

Method Definition:: public static String standardDate()
Parameters List:: none
Method Return:: The current date string.

2.2.2.15 Millimetres, Inches and Points

2.2.2.15.1 Introduction

This section has methods for converting millemetres to and from inches or points (1/72 inch units).

Methods:

Inches to mm - inchesToMM
Inches to mm - inchesToMM
Mm to inches - mmToInches
Mm to inches - mmToInches
Mm to points - mmToPoints
Mm to nearest point - mmToPoints
Points to mm - pointsToMM

2.2.2.15.2 Inches to mm - inchesToMM

Converts inches to mm and returns a double value.

Method Definition:

public static double inchesToMM (double inches)

Parameters List:

inches: Length in inches.

Method Return:

The length in mm.

2.2.2.15.3 Inches to mm - inchesToMM

Convert inches to mm and returns a float value.

Method Definition:

public static float inchesToMM (float inches)

Parameters List:

inches: Length in inches.

Method Return:

The length in mm.

2.2.2.15.4 Mm to inches - mmToInches

Converts mm to inches and returns a double value.

Method Definition:

public static double mmToInches (double mm)

Parameters List:

mm: Length in mm

Method Return:

The length in inches

2.2.2.15.5 Mm to inches - mmToInches

Converts mm to inches and returns a float value.

Method Definition:

public static float mmToInches (float mm)

Parameters List:

mm: Length in mm.

Method Return:

The length in inches.

2.2.2.15.6 Mm to points - mmToPoints

Returns the conversion factor for converting millimetres to points.

Method Definition:: public static double mmToPoints ()
Parameters List:: none
Method Return:: The conversion factor.

2.2.2.15.7 Mm to nearest point - mmToPoints

Converts a length in mm to the nearest integer points length.

Method Definition:

public static int mmToPoints (double mm)

Parameters List:

mm: Length in mm.

Method Return:

The nearest integer length in points.

2.2.2.15.8 Points to mm - pointsToMM

Converts an integer length in points to a lenght in mm.

Method Definition:

public static double pointsToMM (int points)

Parameters List:

points: Length in points (integer).

Method Return:

The length in mm.

2.2.2.16 Colour Methods

2.2.2.16.1 Introduction

This section has some special colour handling methods.

Methods:

Convert HSV to RGB - HSVtoRGB
Pack RGB colours - packRGB
Pack RGB colours - packRGB
Red to blue scale - redToBlueColourScale
Freeze blue color - freezeBlue

2.2.2.16.2 Convert HSV to RGB - HSVtoRGB

This method converts colours from HSV (Hue 0.0-360.0, Saturation 0.0-1.0 and Value 0.0-1.0) to RGB values (Red 0-1.0, Green 0.0-1.0 and Blue 0.0-1.0).

Method Definition:

public static void HSVtoRGB(float[] hsv, float[] rgb)

Parameters List:

hsv: 3 element array containing the input HSV values.
rgb: 3 element array returning the output RGB values.

2.2.2.16.3 Pack RGB colours - packRGB

This method packs the red, green and blue component colours into an integer (3x8 bits).

Method Definition:

public static int packRGB (float r, float g, float b)

Parameters List:

r: Red component 0 - 1.0.
g: Green component 0 - 1.0.
b: Blue component 0 - 1.0.

Method Return:

The integer with the packed components

2.2.2.16.4 Pack RGB colours - packRGB

This method packs the red, green and blue component colours into an integer (3x8 bits).

Method Definition:

public static int packRGB (int r, int g, int b)

Parameters List:

r: Red component 0 - 255.
g: Green component 0 - 255.
b: Blue component 0 - 255.

Method Return:

The integer with the packed components

2.2.2.16.5 Red to blue scale - redToBlueColourScale

This method sets a color scale from red to blue for a given number of values.

Method Definition:

public static Color[] redToBlueColourScale (int nv)

Parameters List:

nv: The number of colour values to be returned.

Method Return:

Array of 'nv' Color objects; colour at index 0 = Red to colour at index (nv-1) = Blue.

2.2.2.16.6 Freeze blue color - freezeBlue

This method returns a specially selected 'freeze blue' colour used originally as a colour to mark areas on a grayscale image in a clear but not excessively bright manner.

Method Definition:: public static Color freezeBlue()
Parameters List:: none
Method Return:: The 'freeze blue' colour

2.2.2.17 Opening & Reading Files

2.2.2.17.1 Introduction

This section contains methods to open an input or an output file for the cases where the filename may either be a local filename or may be specified as a URL. These methods return a Buffered Reader or Writer respectively. There is also a method to read a set of bytes from a buffered input stream.

Methods:

Open input file or URL - openFileOrURL
Open data input stream - openDataInputStream
Open output file or URL - openOutputFileOrURL
Open data output stream - openDataOutputStream
Read bytes - readBytes

2.2.2.17.2 Open input file or URL - openFileOrURL

This method creates a BufferedReader object for a local file or URL.

Method Definition:

public static BufferedReader openFileOrURL(String filnam) throws MalformedURLException, FileNotFoundException, IOException

Parameters List:

filnam: The file/URL name.

Method Return:

The buffered reader.

2.2.2.17.3 Open data input stream - openDataInputStream

This method creates a DataInputStream object for a local file or URL.

Method Definition:

public static DataInputStream openDataInputStream(String filnam) throws MalformedURLException, FileNotFoundException, IOException

Parameters List:

filnam: The file/URL name.

Method Return:

The data input stream.

2.2.2.17.4 Open output file or URL - openOutputFileOrURL

This method creates a BufferedWriter object for a local file or URL.

Method Definition:

public static BufferedWriter openOutputFileOrURL(String filnam) throws MalformedURLException, IOException

Parameters List:

filnam: The file/URL name.

Method Return:

The buffered writer.

2.2.2.17.5 Open data output stream - openDataOutputStream

This method creates a DataOutputStream object for a local file or URL.

Method Definition:

public static DataOutputStream openDataOutputStream(String filnam) throws MalformedURLException, IOException

Parameters List:

filnam: The file/URL name.

Method Return:

The data output stream.

2.2.2.17.6 Read bytes - readBytes

This method reads a sequence of bytes into a byte array from a buffered input stream.

Method Definition:

public static int readBytes (BufferedInputStream bis, byte[] buf, int nbytes) throws IOException

Parameters List:

bis: The buffered input stream from which to read.
buf: The byte array into which the bytes are to be returned.
nbytes: The number of bytes to be read.

Method Return:

The number of unread bytes - should be zero.

2.2.2.18 Fit a Circle

2.2.2.18.1 Introduction

This section consists of a single method to fit the best circle to a set of points.

Method:

Fit a circle - fitCircle

2.2.2.18.2 Fit a circle - fitCircle

This method fits the best circle (least squares - unweighted) to a set of points.

Method Definition:

public static JdlCircle fitCircle(int np, double[] xx, double[] yy, JdlDouble rms, JdlError err)

Parameters List:

np: The number of points to be fitted.
xx: An array holding the 'np' 'x' coordinates.
yy: An array holding the 'np' 'y' coordinates.
rms: Returns the radius rms value.
err: Error return object. If an error was encountered 'err.err' is set to true, an error message is returned in 'err.msg1' and 'err.flag'is set as follows:
= 1, Too few points - at least three must be given
= 2, Singular matrix found

Method Return:

Returns the circle details (null if too few points or singular matrix).

2.2.2.19 Matrix and Vector Methods

2.2.2.19.1 Introduction

This section consists of a set of methods for handling 3x3 matrices and 3 element vectors. Methods for setting up rotation methods are also included. Versions of some of the methods allow for input parameters in Jdl3x3 object or JdlVec object form or in array form. A matrix inversion array for a general size square matrix is also included.

Methods:

Set rotation matrix - rotationMatrix
Set rotation matrix - rotationMatrix
Multiply matrices - multiplyMatrices
Multiply matrices - multiplyMatrices
Multiply matrix and vector - multMatrixVector
Multiply matrix and vector - multMatrixVector
Scale a matrix - scaleMatrix
Scale a matrix - scaleMatrix
Scale a vector - scaleVector
Scale a vector - scaleVector
Add vectors - addVector
Add vectors - addVector
Subtract vectors - subtractVector
Subtract vectors - subtractVector
Normalise vector - normaliseVector
Normalise vector - normaliseVector
Vector magnitude - vectorMagnitude
Vector magnitude - vectorMagnitude
Angle between vectors - vectorAngle
Vector dot product - vectorDotProduct
Vector dot product - vectorDotProduct
Vector cross product - vectorCrossProduct
Vector cross product - vectorCrossProduct
Invert a square matrix - invertMatrix

2.2.2.19.2 Set rotation matrix - rotationMatrix

This method sets up a rotation matrix for a rotation around a requested axis.

Method Definition:

public static Jdl3x3 rotationMatrix (double angle, JdlVec ax)

Parameters List:

angle: The rotation angle around the axis in radians.
ax: The axis vector around which the rotation is to be done.

Method Return:

The required rotation matrix.

2.2.2.19.3 Set rotation matrix - rotationMatrix

This method sets up a rotation matrix for a rotation around a requested axis.

Method Definition:

public static Jdl3x3 rotationMatrix (double angle, double[] axis)

Parameters List:

angle: The rotation angle around the axis in radians.
axis: The axis vector around which the rotation is to be done as a three element array - must be a unit vector.

Method Return:

The required rotation matrix.

2.2.2.19.4 Multiply matrices - multiplyMatrices

This method multiplies two 3x3 matrices.

Method Definition:

public static Jdl3x3 multiplyMatrices(Jdl3x3 mat1, Jdl3x3 mat2)

Parameters List:

mat1: The first 3x3 matrix.
mat2: The second 3x3 matrix.

Method Return:

The product (3x3) matrix = mat1 * mat2.

2.2.2.19.5 Multiply matrices - multiplyMatrices

This method multiplies two 3x3 matrices.

Method Definition:

public static Jdl3x3 multiplyMatrices(double[][] mat1, double[][] mat2)

Parameters List:

mat1: The first 3x3 matrix as an array.
mat2: The second 3x3 matrix as an array.

Method Return:

The product (3x3) matrix = mat1 * mat2.

2.2.2.19.6 Multiply matrix and vector - multMatrixVector

This method multiplies a 3x3 matrix by a vector.

Method Definition:

public static JdlVec multMatrixVector(Jdl3x3 mat, JdlVec vec)

Parameters List:

mat: The 3x3 matrix.
vec: The vector.

Method Return:

The product vector = mat * vec.

2.2.2.19.7 Multiply matrix and vector - multMatrixVector

This method multiplies a 3x3 matrix by a vector.

Method Definition:

public static JdlVec multMatrixVector(double[][] mat, double[] vec)

Parameters List:

mat: The 3x3 matrix as an array.
vec: The vector as a 3 element array.

Method Return:

The product vector = mat * vec.

2.2.2.19.8 Scale a matrix - scaleMatrix

This method scales a 3x3 matrix.

Method Definition:

public static Jdl3x3 scaleMatrix (Jdl3x3 mat, double sc)

Parameters List:

mat: The 3x3 matrix.
sc: The scaling factor.

Method Return:

The scaled matrix = mat * sc.

2.2.2.19.9 Scale a matrix - scaleMatrix

This method scales a 3x3 matrix.

Method Definition:

public static Jdl3x3 scaleMatrix (double[][] mat, double sc)

Parameters List:

mat: The 3x3 matrix as an array.
sc: The scaling factor.

Method Return:

The scaled matrix = mat * sc.

2.2.2.19.10 Scale a vector - scaleVector

This method scales a 3 element vector.

Method Definition:

public static JdlVec scaleVector (JdlVec vec, double sc)

Parameters List:

vec: The 3 element vector.
sc: The scaling factor.

Method Return:

The scaled vector = vec * sc.

2.2.2.19.11 Scale a vector - scaleVector

This method scales a 3 element vector.

Method Definition:

public static JdlVec scaleVector (double[] vec, double sc)

Parameters List:

vec: The 3 element vector as an array.
sc: The scaling factor.

Method Return:

The scaled vector = vec * sc.

2.2.2.19.12 Add vectors - addVector

This method adds two 3 element vectors.

Method Definition:

public static JdlVec addVector (JdlVec vec1, JdlVec vec2)

Parameters List:

vec1: The first 3 element vector.
vec2: The second 3 element vector.

Method Return:

The vector sum vector vec1 + vec2.

2.2.2.19.13 Add vectors - addVector

This method adds two 3 element vectors.

Method Definition:

public static JdlVec addVector (double[] vec1, double[] vec2)

Parameters List:

vec1: The first 3 element vector as an array.
vec2: The second 3 element vector as an array.

Method Return:

The vector sum vector vec1 + vec2.

2.2.2.19.14 Subtract vectors - subtractVector

This method subtracts two 3 element vectors.

Method Definition:

public static JdlVec subtractVector (JdlVec vec1, JdlVec vec2)

Parameters List:

vec1: The first 3 element vector.
vec2: The second 3 element vector.

Method Return:

The vector difference vector vec1 - vec2.

2.2.2.19.15 Subtract vectors - subtractVector

This method subtracts two 3 element vectors.

Method Definition:

public static JdlVec subtractVector (double[] vec1, double[] vec2)

Parameters List:

vec1: The first 3 element vector as an array.
vec2: The second 3 element vector as an array.

Method Return:

The vector difference vector vec1 - vec2.

2.2.2.19.16 Normalise vector - normaliseVector

This method calculate a normalised vector.

Method Definition:

public static JdlVec normaliseVector (JdlVec vec)

Parameters List:

vec: The 3 element vector.

Method Return:

The normalised vector.

2.2.2.19.17 Normalise vector - normaliseVector

This method calculate a normalised vector.

Method Definition:

public static JdlVec normaliseVector (double[] vec)

Parameters List:

vec: The 3 element vector as a 3 element array.

Method Return:

The normalised vector.

2.2.2.19.18 Vector magnitude - vectorMagnitude

This method calculates the magnitude of a vector.

Method Definition:

public static double vectorMagnitude (JdlVec vec)

Parameters List:

vec: The 3 element vector.

Method Return:

The vector magnitude.

2.2.2.19.19 Vector magnitude - vectorMagnitude

This method calculates the magnitude of a vector.

Method Definition:

public static double vectorMagnitude (double[] vec)

Parameters List:

vec: The 3 element vector as a 3 element array.

Method Return:

The vector magnitude.

2.2.2.19.20 Angle between vectors - vectorAngle

This method calculates the angle between two 3 element vectors.

Method Definition:

public static double vectorAngle(JdlVec vec1, JdlVec vec2)

Parameters List:

vec1: The first vector.
vec2: The second vector.

Method Return:

The angle between the two vectors in degrees.

2.2.2.19.21 Vector dot product - vectorDotProduct

This method calculates the dot product two 3 element vectors.

Method Definition:

public static double vectorDotProduct(JdlVec vec1, JdlVec vec2)

Parameters List:

vec1: The first vector.
vec2: The second vector.

Method Return:

The dot product of the two vectors.

2.2.2.19.22 Vector dot product - vectorDotProduct

This method calculates the dot product two 3 element vectors as arrays.

Method Definition:

public static double vectorDotProduct(double[] v1, double[] v2)

Parameters List:

v1: The first vector 3 element array.
v2: The second vector 3 element array.

Method Return:

The dot product of the two vectors.

2.2.2.19.23 Vector cross product - vectorCrossProduct

This method calculates the cross product two 3 element vectors.

Method Definition:

public static JdlVec vectorCrossProduct(JdlVec vec1, JdlVec vec2)

Parameters List:

v1: The first vector.
v2: The second vector.

Method Return:

The cross product of the two vectors.

2.2.2.19.24 Vector cross product - vectorCrossProduct

This method calculates the cross product two 3 element vectors as arrays.

Method Definition:

public static JdlVec vectorCrossProduct(double[] v1, double[] v2)

Parameters List:

v1: The first vector 3 element array.
v2: The second vector 3 element array.

Method Return:

The cross product of the two vectors.

2.2.2.19.25 Invert a square matrix - invertMatrix

This method inverts a matrix by elimination with partial pivoting.

Method Definition:

public static double[][] invertMatrix (double[][] mat, JdlDouble determ, JdlError err)

Parameters List:

mat: The square matix to be inverted as a 2-D double array.
determ: Returns the determinant
err: Returns an error code. If OK err.err will be false. If err.err is true then a singular matrix was found; err.flag will be set to 1 and an error message will be returned in err.msg1. If the input matrix was not square err.flag will be set to -1.

Method Return:

The inverted matrix (null if a singular matrix was found)

2.2.2.20 Byte Manipulation

2.2.2.20.1 Introduction

The section contains methods to pack bytes into an integer array and to perform byte swapping as may be required when handling binary data written by different computer systems.

Methods:

Pack bytes - byteToIntArray
Swap bytes - swapI2
Swap bytes - swapI4