GXSTR class

class geosoft.gx.GXSTR
This library is not a class. Use the STR library functions
to work with and manipulate string variables. Since the
GX Programming Language does not provide string literal
tokens, you must use these functions for any string operations
you want to perform.
static char_n((GXContext)ctx, (str)arg1, (int)arg2, (int)arg3) → int:
Returns the ASCII value of the n'th character.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – string
  • arg2 (int) – character to get
  • arg3 (int) – maximum string length (unused)
Returns:

ASCII value of n’th character in string. The first character is 0.
Return type:

int

New in version 5.0.0.

static count_tokens((GXContext)ctx, (str)arg1, (str)arg2) → int:
Counts number of tokens.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – string to tokenize
  • arg2 (str) – delimiter characters
Returns:

Number of tokens in the string.
Return type:

int

New in version 5.0.0.

Note:

Delimiters are "soft" in that one or more delimiters
is considered a single delimiter, and preceding and
trailing delimiters are ignored.

DO NOT use this function except in GXC code. The corresponding
geosoft.gx.GXSTR.get_token() function will not operate correctly in GX.Net code.
static escape((GXContext)ctx, (str_ref)arg1, (int)arg2) → None:
Convert/replace escape sequences in strings.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.6.

Note:

Escape characters:

          a      bell
          b      backspace
          f      formfeed
          n      new line
          r      carriage return
          t      tab
          v      vertical tab
          "      quote character
          x      take 'x' literally
          \      backslash
          ooo    octal up to 3 characters
          xhh    hex up to 2 characters

A common use of this function is to convert double-quote characters in
a user unput string to " so the string can be placed in a tokenized
string.
static file_combine_parts((GXContext)ctx, (str)arg1, (str)arg2, (str)arg3, (str)arg4, (str)arg5, (str_ref)arg6) → None:
Combine file parts to build a file name.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – drive
  • arg2 (str) – directory
  • arg3 (str) – name
  • arg4 (str) – extension
  • arg5 (str) – qualifiers
  • arg6 (geosoft.gx.str_ref) – destination string, can be same as input
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static file_ext((GXContext)ctx, (str)arg1, (str)arg2, (str_ref)arg3, (int)arg4) → None:
Add a file extension onto a file name string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static file_name_part((GXContext)ctx, (str)arg1, (str_ref)arg2, (int)arg3) → None:
Get part of a file name.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_crc((GXContext)ctx, (int)arg1, (str_ref)arg2, (int)arg3) → None:
Convert a GX CRC value to a string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_date((GXContext)ctx, (float)arg1, (str_ref)arg2, (int)arg3, (int)arg4) → None:
Convert a GX real to a date string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_double((GXContext)ctx, (float)arg1, (str_ref)arg2, (int)arg3, (int)arg4, (int)arg5) → None:
Convert a GX real to a string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_i((GXContext)ctx, (int)arg1, (str_ref)arg2, (int)arg3) → None:
Convert a GX int to a string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_r((GXContext)ctx, (float)arg1, (str_ref)arg2, (int)arg3, (int)arg4) → None:
Convert a GX real to a string with significant digits.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (float) – value to format
  • arg2 (geosoft.gx.str_ref) – Resulting string
  • arg3 (int) – Width of the field
  • arg4 (int) – Significant digits
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_r2((GXContext)ctx, (float)arg1, (str_ref)arg2, (int)arg3, (int)arg4) → None:
Convert a GX real to a string with given decimals.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (float) – value to format
  • arg2 (geosoft.gx.str_ref) – Resulting string
  • arg3 (int) – Width of the field
  • arg4 (int) – Decimals
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static format_time((GXContext)ctx, (float)arg1, (str_ref)arg2, (int)arg3, (int)arg4, (int)arg5) → None:
Convert a GX real to a time string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static gen_group_name((GXContext)ctx, (str)arg1, (str)arg2, (str)arg3, (str_ref)arg4) → None:
Generate a group name string
from type string, database and channel(optional) strings..
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – input type string (static part)
  • arg2 (str) – input db string
  • arg3 (str) – input ch string (could be 0 length)
  • arg4 (geosoft.gx.str_ref) – output group name string
Returns:

Nothing
Return type:

None

New in version 5.1.4.

Note:

The output group name string is formed in the way of typestr_dbstr_chstr.
If the database/channel strings is too long to fit the output string
(max total length of 1040, including the NULL ending), then
the typestr will always be kept the full length to be the first part,
while the dbstr and/or chstr will be shortened to be the
second and/or third part of the output string.

See also

GenNewGroupName_MVIEW

static get_char((GXContext)ctx, (str)arg1) → int:
Returns the ASCII value of a character.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – string to return ascii value of first character
Returns:

ASCII value of first character in string.
Return type:

int

New in version 5.0.0.

static get_m_file((GXContext)ctx, (str)arg1, (str_ref)arg2, (int)arg3) → None:
Get the indexed filepath from a multiple filepath string
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

The multifile string must use '|' as a delimiter.
Do not pass a string after calling geosoft.gx.GXSTR.tokenize().
static get_token((GXContext)ctx, (str_ref)arg1, (str)arg2, (int)arg3) → None:
Get a token from a tokenized string.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (geosoft.gx.str_ref) – destination string
  • arg2 (str) – tokenized string
  • arg3 (int) – token number wanted (0 is the first!)
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

Call geosoft.gx.GXSTR.tokens()  to prepare the tokenized
string.
You MUST NOT get tokens beyond number of tokens returned
by geosoft.gx.GXSTR.tokens() or geosoft.gx.GXSTR.tokens2().
The first token has index 0.

DO NOT use this function except in GXC code.
geosoft.gx.GXSTR.get_token() function will not operate correctly in GX.Net code.

See also

geosoft.gx.GXSTR.tokens(), GetToken_STR

static justify((GXContext)ctx, (str)arg1, (str_ref)arg2, (int)arg3, (int)arg4) → None:
Justify a string
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

If the string is too big to fit in the number of display characters,
the output string will be "**" justified as specified.
static make_alpha((GXContext)ctx, (str_ref)arg1) → None:
Turns all non alpha-numeric characters into an _.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.1.8.

Note:

THE STRING IS MODIFIED.
static parse_list((GXContext)ctx, (str)arg1, (GXVV)arg2) → None:
Parse a tokenized list to get a selection list.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.1.

Note:

Given a list such as "1,3,4,6-9,12", it fills the
input buffer with 1 if the number is selected,
0 if not. The items are delimited with spaces
or commas, and ranges are acceptable, either using
a "-" or ":", e.g.  3-6 and 3:6 both mean 3,4,5, and 6.
Only values from 0 to one less than the buffer length
are used.  Out-of-range values are ignored.
static printf((GXContext)ctx, (str_ref)arg1, (str)arg2) → None:
Variable Argument PrintF function
Parameters:
Returns:

Nothing
Return type:

None

New in version 7.3.0.

static remove_qualifiers((GXContext)ctx, (str)arg1, (str_ref)arg2) → None:
Remove file qualifiers from a file name
Parameters:
Returns:

Nothing
Return type:

None

New in version 7.0.1.

static replace_char((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3) → None:
Replaces characters in a string.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (geosoft.gx.str_ref) – string to modify
  • arg2 (str) – character to replace (first character only)
  • arg3 (str) – replacement character (first character only)
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

If the input replacement character is "", then the
string will be truncated at the first character to replace.
static replace_char2((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3) → None:
Replaces characters in a string, supports simple removal.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (geosoft.gx.str_ref) – string to modify
  • arg2 (str) – character to replace (first character only)
  • arg3 (str) – replacement character (first character only)
Returns:

Nothing
Return type:

None

New in version 6.3.0.

Note:

If the replacement character is "" (NULL character)
then the character to replace is removed from the
input string, and the string is shortened.
static replace_match_string((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3) → None:
Replaces all occurances of match string by replacement string with case sensitive.
Parameters:
Returns:

Nothing
Return type:

None

New in version 7.0.1.

Note:

If the replacement string is "" (NULL character)
then the string to replace is removed from the
input string, and the string is shortened.
static replace_multi_char((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3) → None:
Replaces multiple characters in a string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.1.5.

Note:

The number of characters to replace must equal
the number of replacement characters.
static replace_non_ascii((GXContext)ctx, (str_ref)arg1, (str)arg2) → None:
Replace non-ASCII characters in a string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 6.0.0.

Note:

All characthers > 127 will be replaced by the first character
of the replacement string.
static replacei_match_string((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3) → None:
Replaces all occurances of match string by replacement string with case insensitive.
Parameters:
Returns:

Nothing
Return type:

None

New in version 7.0.1.

Note:

If the replacement string is "" (NULL character)
then the string to replace is removed from the
input string, and the string is shortened.
static scan_date((GXContext)ctx, (str)arg1, (int)arg2) → float:
Convert a date string to a GX real.
Parameters:
Returns:

Resulting Real, rDUMMY if conversion fails.
Return type:

float

New in version 6.0.1.

Note:

OLD usage, use ScanForm_STR instead.
static scan_form((GXContext)ctx, (str)arg1, (int)arg2) → float:
Convert a formated string to a real.
Parameters:
Returns:

Resulting Real, rDUMMY if conversion fails.
Return type:

float

New in version 6.0.1.

static scan_i((GXContext)ctx, (str)arg1) → int:
Convert a string to a GX int.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – String to convert to an integer
Returns:

Resulting Integer, iDUMMY is bad integer
Return type:

int

New in version 6.0.1.

static scan_r((GXContext)ctx, (str)arg1) → float:
Convert a string to a GX real.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – String to convert to a real
Returns:

Resulting Real, rDUMMY if bad string.
Return type:

float

New in version 6.0.1.

static scan_time((GXContext)ctx, (str)arg1, (int)arg2) → float:
Convert a time string to a GX real.
Parameters:
Returns:

Resulting Real, rDUMMY if conversion fails.
Return type:

float

New in version 6.0.1.

Note:

OLD usage, use ScanForm_STR instead.
static set_char((GXContext)ctx, (str_ref)arg1, (int)arg2) → None:
Set a string's first character using an ASCII value of a character.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.1.4.

static set_char_n((GXContext)ctx, (str_ref)arg1, (int)arg2, (int)arg3) → None:
Set the n'th character of a string using an ASCII value
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.1.4.

static split_string((GXContext)ctx, (str_ref)arg1, (str)arg2, (str_ref)arg3) → None:
Splits a string in two on a character.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

The original string is modified by terminating it
at the character split.

The part of the string past the character split is
copied to the split string.

Split characters in quoted strings are ignored.

This function is mainly intended to separate comments
from control file strings.
static str_mask((GXContext)ctx, (str)arg1, (str)arg2) → int:
Case sensitive comparison of two strings.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – mask
  • arg2 (str) – string to test
Returns:

0 if string does not match mask. 1 if string matches mask.
Return type:

int

New in version 5.0.0.

Note:

Mask characters '*' - matches any one or more up to
                      next character
                '?' - matches one character

Test is case sensitive
static str_min((GXContext)ctx, (str_ref)arg1) → int:
Remove spaces and tabs and return length
Parameters:
Returns:

String length.
Return type:

int

New in version 5.0.0.

Note:

String may be modified. This function should not be
used to determine if a file name string is defined, because
a valid file name can contain spaces, and once "tested" the
name will be altered. Instead, use geosoft.gx.GXSTR.str_min2(), or use
geosoft.gx.GXSYS.file_exist() to see if the file actually exists.
static str_min2((GXContext)ctx, (str)arg1) → int:
Length less spaces and tabs, string unchanged.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – string to find the min length of
Returns:

String length.
Return type:

int

New in version 5.0.0.

static str_str((GXContext)ctx, (str)arg1, (str)arg2, (int)arg3) → int:
Scan a string for the occurrence of a given substring.
Parameters:
Returns:

-1 if the substring does not occur in the string Index of first matching location if found
Return type:

int

New in version 5.1.6.

static strcat((GXContext)ctx, (str_ref)arg1, (str)arg2) → None:
This method contatinates a string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static strcmp((GXContext)ctx, (str)arg1, (str)arg2, (int)arg3) → int:
This method compares two strings and returns these values
Parameters:
Returns:

A < B -1 A == B 0 A > B 1
Return type:

int

New in version 5.0.0.

static strcpy((GXContext)ctx, (str_ref)arg1, (str)arg2) → None:
This method copies a string into another string.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static stri_mask((GXContext)ctx, (str)arg1, (str)arg2) → int:
Case insensitive comparison of two strings.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – mask
  • arg2 (str) – string to test
Returns:

0 if string does not match mask. 1 if string matches mask.
Return type:

int

New in version 5.0.0.

Note:

Mask characters '*' - matches any one or more up to
                      next character
                '?' - matches one character

Test is case insensitive
static strins((GXContext)ctx, (str_ref)arg1, (int)arg2, (str)arg3) → None:
This method inserts a string at a specified position.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.1.8.

Note:

If the specified position does not fall within the current string
the source string will simply be Concatenated.
static strlen((GXContext)ctx, (str)arg1) → int:
Returns the length of a string.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (str) – string to find the length of
Returns:

String length.
Return type:

int

New in version 5.0.0.

static strncmp((GXContext)ctx, (str)arg1, (str)arg2, (int)arg3, (int)arg4) → int:
Compares two strings to a given number of characters.
Parameters:
Returns:

A < B -1 A == B 0 A > B 1
Return type:

int

New in version 5.0.5.

static substr((GXContext)ctx, (str_ref)arg1, (str)arg2, (int)arg3, (int)arg4) → None:
Extract part of a string.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (geosoft.gx.str_ref) – destination string
  • arg2 (str) – origin string
  • arg3 (int) – start location
  • arg4 (int) – number of characters
Returns:

Nothing
Return type:

None

New in version 6.2.0.

Note:

The destination string length will be less than the
requested length if the substring is not fully enclosed
in the origin string.
static to_lower((GXContext)ctx, (str_ref)arg1) → None:
Convert a string to lower case.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static to_upper((GXContext)ctx, (str_ref)arg1) → None:
Convert a string to upper case.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

static tokenize((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3, (str)arg4, (str)arg5) → int:
Tokenize a string based on any characters.
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (geosoft.gx.str_ref) – str - String containing token(s)
  • arg2 (str) – szSoft - Soft delimiters (spaces/tabs)
  • arg3 (str) – szHard - Hard delimiters (commas)
  • arg4 (str) – szEsc - Escape delimiters (back-slash)
  • arg5 (str) – szQuote- Quote delimiters (quote characters)
Returns:

number of tokens
Return type:

int

New in version 5.0.0.

Note:

This uses a finite state machine to tokenize on these
rules:

1. Any one character following an escape delimiter is
   treated as a normal character.

2. Any characters inside a quote string are treated as
   normal characters.

3. Any number of Soft delimiters in sequence without a
   hard delimiter are treated as one hard delimited.

4. Any number of soft delimiters can preceed or follow
   a hard delimiter and are ignored.


EXAMPLE

Soft = [ ]   Hard = [,]   Escape = []    Quote = ["]

[this is a , , the "test," of   ,  ," my delimite  fi,]

Results in:

[this] [is] [a] [] [the] ["test,"] [of] [,"] [my] [delimite] [fi] []


NOT use this function except in GXC code. The corresponding
etToken_STR function will not operate correctly in GX.Net code.

See also

GetToken_STR

static tokens((GXContext)ctx, (str_ref)arg1, (str)arg2) → int:
Tokenize a string
Parameters:
Returns:

number of tokens, maximum is 2048
Return type:

int

New in version 5.0.0.

Note:

Delimiters in the string are reduced to a single NULL.
Delimiters withing double quoted strings are ignored.
Use GetToken_STR to extract tokens.

DO NOT use this function except in GXC code. The corresponding
geosoft.gx.GXSTR.get_token() function will not operate correctly in GX.Net code.

See also

geosoft.gx.GXSTR.tokens2(), GetToken_STR

static tokens2((GXContext)ctx, (str_ref)arg1, (str)arg2, (str)arg3, (str)arg4, (str)arg5) → int:
General tokenize a string
Parameters:
  • ctx (geosoft.gx.GXContext) – The GX execution context
  • arg1 (geosoft.gx.str_ref) – string to tokenize
  • arg2 (str) – szSoft - Soft delimiters (spaces/tabs)
  • arg3 (str) – szHard - Hard delimiters (commas)
  • arg4 (str) – szEsc - Escape delimiters (back-slash)
  • arg5 (str) – szQuote- Quote delimiters (quote characters)
Returns:

Number of Tokens
Return type:

int

New in version 5.0.0.

Note:

This function is for old GX compatibility only.
See geosoft.gx.GXSTR.tokenize().

DO NOT use this function except in GXC code. The corresponding
geosoft.gx.GXSTR.get_token() function will not operate correctly in GX.Net code.
static trim_quotes((GXContext)ctx, (str_ref)arg1) → None:
Remove double quotes.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

THE STRING IS MODIFIED.
This method goes through the string and removes all spaces in a
string except those enclosed in quotes. It then removes
any quotes. It is usfull for trimming unwanted spaces from
an input string but allows the user to use quotes as well.
If a quote follows a backslash, the quote is retained and
the backslash is deleted. These quotes are NOT treated as
delimiters.
static trim_space((GXContext)ctx, (str_ref)arg1, (int)arg2) → None:
Remove leading and/or trailing whitespace.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

THE STRING IS MODIFIED.
Whitespace characters are defined as space, tab, carriage return,
new line, vertical tab or formfeed (0x09 to 0x0D, 0x20)
static un_quote((GXContext)ctx, (str_ref)arg1) → None:
Remove double quotes from string
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

Note:

THE STRING IS MODIFIED.
The pointers will be advanced past a first character
quote and a last character quote will be set to .0'.
Both first and last characters must be quotes for the
triming to take place.
static xyz_line((GXContext)ctx, (str)arg1, (str_ref)arg2) → None:
Make a valid XYZ line name from a valid DB line name.
Parameters:
Returns:

Nothing
Return type:

None

New in version 5.0.0.

FILE_EXT constants

Extension option
gx.FILE_EXT_ADD_IF_NONE = 0
will add the extension only if no extension is present.
gx.FILE_EXT_FORCE = 1
will cause a renaming of the file extension to the new extension.

STR_CASE constants

Case sensitivity
gx.STR_CASE_TOLERANT = 0
gx.STR_CASE_SENSITIVE = 1

STR_ESCAPE constants

How to handle escape
gx.ESCAPE_CONVERT = 0
Converts non-standard characters in a string to escape sequences.
gx.ESCAPE_REPLACE = 1
Replaces escape sequences with original characters.

STR_FILE_PART constants

Parts of a path string
gx.STR_FILE_PART_NAME = 0
File Name
gx.STR_FILE_PART_EXTENSION = 1
Extension
gx.STR_FILE_PART_DIRECTORY = 2
Directory
gx.STR_FILE_PART_VOLUME = 3
Drive
gx.STR_FILE_PART_QUALIFIERS = 4
Qualifiers
gx.STR_FILE_PART_NAME_EXTENSION = 5
Name and the Extension together
gx.STR_FILE_PART_FULLPATH_NO_QUALIFIERS = 6
Full name of file with no qualifiers

STR_JUSTIFY constants

String justification style
gx.STR_JUSTIFY_LEFT = 0
gx.STR_JUSTIFY_CENTER = 1
gx.STR_JUSTIFY_RIGHT = 2

STR_TRIM constants

What to trim
gx.STR_TRIMRIGHT = 1
gx.STR_TRIMLEFT = 2
gx.STR_TRIMBOTH = 3