GXSTR class¶
-
class
GXSTR
(handle=0)[source]¶ GXSTR class.
This library is not a class. Use the
GXSTR
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.-
classmethod
char_
(str_val)[source]¶ Returns the ASCII value of a character.
- Parameters
str_val (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.
License: Geosoft Open License
-
classmethod
char_n
(str_val, c, max)[source]¶ Returns the ASCII value of the n’th character.
- Parameters
str_val (str) – String
c (int) – Character to get
max (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.
License: Geosoft Open License
-
classmethod
count_tokens
(str_val, delims)[source]¶ Counts number of tokens.
- Parameters
str_val (str) – String to tokenize
delims (str) – Delimiter characters
- Returns
Number of tokens in the string.
- Return type
int
New in version 5.0.
License: Geosoft Open License
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
get_token
function will not operate correctly in GX.Net code.
-
classmethod
escape
(str_val, opt)[source]¶ Convert/replace escape sequences in strings.
- Parameters
str_val (str_ref) – String to modify
opt (int) – STR_ESCAPE constants
New in version 5.0.6.
License: Geosoft Open License
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.
-
classmethod
file_combine_parts
(drive, dir, file, ext, qual, file_name)[source]¶ Combine file parts to build a file name.
- Parameters
drive (str) – Drive
dir (str) – Directory
file (str) – Name
ext (str) – Extension
qual (str) – Qualifiers
file_name (str_ref) – Destination string, can be same as input
New in version 5.0.
License: Geosoft Open License
-
classmethod
file_ext
(ifile, ext, ofile, opt)[source]¶ Add a file extension onto a file name string.
- Parameters
ifile (str) – File name to extend
ext (str) – Extension if “”, extenstion and ‘.’ are stripped.
ofile (str_ref) – Extended file name (can be same as input)
opt (int) – FILE_EXT constants
New in version 5.0.
License: Geosoft Open License
-
classmethod
file_name_part
(file, file_part, part)[source]¶ Get part of a file name.
- Parameters
file (str) – File name
file_part (str_ref) – Destination string, can be same as input
part (int) – STR_FILE_PART constants
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_crc
(pul_crc, buff, width)[source]¶ Convert a GX CRC value to a string.
- Parameters
pul_crc (int) – CRC value to format
buff (str_ref) – Resulting string
width (int) – Width of the field
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_date
(real, buff, width, type)[source]¶ Convert a GX real to a date string.
- Parameters
real (float) – Date value in decimal years to format
buff (str_ref) – Resulting string
width (int) – Width of the field
type (int) – DATE_FORMAT constants
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_double
(real, buff, type, width, dec)[source]¶ Convert a GX real to a string.
- Parameters
real (float) – Value to format
buff (str_ref) – Resulting string
type (int) – GS_FORMATS constants
width (int) – Width of the field
dec (int) – Significant digits/decimals
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_i
(value, buff, width)[source]¶ Convert a GX int to a string.
- Parameters
value (int) – Value to format
buff (str_ref) – Resulting string
width (int) – Width of the field
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_r
(real, buff, width, sig)[source]¶ Convert a GX real to a string with significant digits.
- Parameters
real (float) – Value to format
buff (str_ref) – Resulting string
width (int) – Width of the field
sig (int) – Significant digits
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_r2
(real, buff, width, sig)[source]¶ Convert a GX real to a string with given decimals.
- Parameters
real (float) – Value to format
buff (str_ref) – Resulting string
width (int) – Width of the field
sig (int) – Decimals
New in version 5.0.
License: Geosoft Open License
-
classmethod
format_time
(real, buff, width, deci, type)[source]¶ Convert a GX real to a time string.
- Parameters
real (float) – Time value in decimal hours to format
buff (str_ref) – Resulting string
width (int) – Width of the field
deci (int) – Decimals to format with
type (int) – TIME_FORMAT constants
New in version 5.0.
License: Geosoft Open License
-
classmethod
gen_group_name
(istr1, istr2, istr3, ostr)[source]¶ Generate a group name string from type string, database and channel(optional) strings..
- Parameters
istr1 (str) – Input type string (static part)
istr2 (str) – Input db string
istr3 (str) – Input ch string (could be 0 length)
ostr (str_ref) – Output group name string
New in version 5.1.4.
License: Geosoft Open License
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
-
classmethod
get_m_file
(in_str, out_str, index)[source]¶ Get the indexed filepath from a multiple filepath string
- Parameters
in_str (str) – Input multifile string
out_str (str_ref) – Output filepath string
index (int) – Index of file
New in version 5.0.
License: Geosoft Open License
Note: The multifile string must use ‘|’ as a delimiter. Do not pass a string after calling
tokenize
.
-
classmethod
get_token
(dest, orig, tok)[source]¶ Get a token from a tokenized string.
- Parameters
dest (str_ref) – Destination string
orig (str) – Tokenized string
tok (int) – Token number wanted (0 is the first!)
New in version 5.0.
License: Geosoft Open License
Note: Call
tokens
to prepare the tokenized string. You MUST NOT get tokens beyond number of tokens returned bytokens
ortokens2
. The first token has index 0.DO NOT use this function except in GXC code.
get_token
function will not operate correctly in GX.Net code.See also
tokens
, GetToken_STR
-
is_null
()[source]¶ Check if this is a null (undefined) instance
- Returns
True if this is a null (undefined) instance, False otherwise.
- Return type
bool
-
classmethod
justify
(in_str, out_str, width, just)[source]¶ Justify a string
- Parameters
in_str (str) – String to justify
out_str (str_ref) – Result string, can be same as input
width (int) – Justification width
just (int) – STR_JUSTIFY constants
New in version 5.0.
License: Geosoft Open License
Note: If the string is too big to fit in the number of display characters, the output string will be “**” justified as specified.
-
classmethod
make_alpha
(str_val)[source]¶ Turns all non alpha-numeric characters into an _.
- Parameters
str_val (str_ref) – String to trim
New in version 5.1.8.
License: Geosoft Open License
Note: THE STRING IS MODIFIED.
-
classmethod
parse_list
(str_val, gvv)[source]¶ Parse a tokenized list to get a selection list.
- Parameters
str_val (str) – String to be parsed
gvv (GXVV) – Selection Buffer to fill
New in version 5.0.1.
License: Geosoft Open License
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.
-
classmethod
printf
(dest, mask)[source]¶ Variable Argument PrintF function
- Parameters
dest (str_ref) – Destination string
mask (str) – Pattern string
New in version 7.3.
License: Geosoft Open License
-
classmethod
remove_qualifiers
(ifile, ofile)[source]¶ Remove file qualifiers from a file name
- Parameters
ifile (str) – Input file name
ofile (str_ref) – Output file name (can be same as input)
New in version 7.0.1.
License: Geosoft Open License
-
classmethod
replace_char
(istr, old, new_char)[source]¶ Replaces characters in a string.
- Parameters
istr (str_ref) – String to modify
old (str) – Character to replace (first character only)
new_char (str) – Replacement character (first character only)
New in version 5.0.
License: Geosoft Open License
Note: If the input replacement character is “”, then the string will be truncated at the first character to replace.
-
classmethod
replace_char2
(istr, old, new_char)[source]¶ Replaces characters in a string, supports simple removal.
- Parameters
istr (str_ref) – String to modify
old (str) – Character to replace (first character only)
new_char (str) – Replacement character (first character only)
New in version 6.3.
License: Geosoft Open License
Note: If the replacement character is “” (NULL character) then the character to replace is removed from the input string, and the string is shortened.
-
classmethod
replace_match_string
(istr, old, new_str)[source]¶ Replaces all occurances of match string by replacement string with case sensitive.
- Parameters
istr (str_ref) – Destination String
old (str) – Match string to replace
new_str (str) – Replacement string
New in version 7.0.1.
License: Geosoft Open License
Note: If the replacement string is “” (NULL character) then the string to replace is removed from the input string, and the string is shortened.
-
classmethod
replace_multi_char
(istr, old, new_char)[source]¶ Replaces multiple characters in a string.
- Parameters
istr (str_ref) – String to modify
old (str) – Characters to replace
new_char (str) – Replacement characters
New in version 5.1.5.
License: Geosoft Open License
Note: The number of characters to replace must equal the number of replacement characters.
-
classmethod
replace_non_ascii
(str_val, rpl)[source]¶ Replace non-ASCII characters in a string.
- Parameters
str_val (str_ref) – String to modify
rpl (str) – Replacement character
New in version 6.0.
License: Geosoft Open License
Note: All characthers > 127 will be replaced by the first character of the replacement string.
-
classmethod
replacei_match_string
(istr, old, new_str)[source]¶ Replaces all occurances of match string by replacement string with case insensitive.
- Parameters
istr (str_ref) – Destination String
old (str) – Match string to replace
new_str (str) – Replacement string
New in version 7.0.1.
License: Geosoft Open License
Note: If the replacement string is “” (NULL character) then the string to replace is removed from the input string, and the string is shortened.
-
classmethod
scan_date
(str_val, type)[source]¶ Convert a date string to a GX real.
- Parameters
str_val (str) – Date string
type (int) – DATE_FORMAT constants
- Returns
Resulting Real,
rDUMMY
if conversion fails.- Return type
float
New in version 6.0.1.
License: Geosoft Open License
Note: OLD usage, use ScanForm_STR instead.
-
classmethod
scan_form
(str_val, type)[source]¶ Convert a formated string to a real.
- Parameters
str_val (str) – Date string
type (int) – GS_FORMATS constants
- Returns
Resulting Real,
rDUMMY
if conversion fails.- Return type
float
New in version 6.0.1.
License: Geosoft Open License
-
classmethod
scan_i
(str_val)[source]¶ Convert a string to a GX int.
- Parameters
str_val (str) – String to convert to an integer
- Returns
Resulting Integer,
iDUMMY
is bad integer- Return type
int
New in version 6.0.1.
License: Geosoft Open License
-
classmethod
scan_r
(str_val)[source]¶ Convert a string to a GX real.
- Parameters
str_val (str) – String to convert to a real
- Returns
Resulting Real,
rDUMMY
if bad string.- Return type
float
New in version 6.0.1.
License: Geosoft Open License
-
classmethod
scan_time
(str_val, type)[source]¶ Convert a time string to a GX real.
- Parameters
str_val (str) – Date string
type (int) – TIME_FORMAT constants
- Returns
Resulting Real,
rDUMMY
if conversion fails.- Return type
float
New in version 6.0.1.
License: Geosoft Open License
Note: OLD usage, use ScanForm_STR instead.
-
classmethod
set_char
(str_val, ascii)[source]¶ Set a string’s first character using an ASCII value of a character.
- Parameters
str_val (str_ref) – String
ascii (int) – ASCII value
New in version 5.1.4.
License: Geosoft Open License
-
classmethod
set_char_n
(str_val, c, ascii)[source]¶ Set the n’th character of a string using an ASCII value
- Parameters
str_val (str_ref) – String
c (int) – Character to set
ascii (int) – ASCII value
New in version 5.1.4.
License: Geosoft Open License
-
classmethod
split_string
(origstr, ch, split)[source]¶ Splits a string in two on a character.
- Parameters
New in version 5.0.
License: Geosoft Open License
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.
-
classmethod
str_mask
(mask, test)[source]¶ Case sensitive comparison of two strings.
- Parameters
mask (str) – Mask
test (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.
License: Geosoft Open License
Note: Mask characters ‘*’ - matches any one or more up to next character ‘?’ - matches one character
Test is case sensitive
-
classmethod
str_min
(str_val)[source]¶ Remove spaces and tabs and return length
- Parameters
str_val (str_ref) – String to find the min length of
- Returns
String length.
- Return type
int
New in version 5.0.
License: Geosoft Open License
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
str_min2
, or useGXSYS.file_exist
to see if the file actually exists.
-
classmethod
str_min2
(str_val)[source]¶ Length less spaces and tabs, string unchanged.
- Parameters
str_val (str) – String to find the min length of
- Returns
String length.
- Return type
int
New in version 5.0.
License: Geosoft Open License
-
classmethod
str_str
(str_val, sub, case_sensitive)[source]¶ Scan a string for the occurrence of a given substring.
- Parameters
str_val (str) – String to scan
sub (str) – String to look for
case_sensitive (int) – STR_CASE constants
- 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.
License: Geosoft Open License
-
classmethod
strcat
(dest, orig)[source]¶ This method contatinates a string.
- Parameters
dest (str_ref) – Destination String
orig (str) – String to add
New in version 5.0.
License: Geosoft Open License
-
classmethod
strcmp
(first, second, case_sensitive)[source]¶ This method compares two strings and returns these values
- Parameters
first (str) – String A
second (str) – String B
case_sensitive (int) – STR_CASE constants
- Returns
A < B -1 A == B 0 A > B 1
- Return type
int
New in version 5.0.
License: Geosoft Open License
-
classmethod
strcpy
(dest, orig)[source]¶ This method copies a string into another string.
- Parameters
dest (str_ref) – Destination string
orig (str) – Origin string
New in version 5.0.
License: Geosoft Open License
-
classmethod
stri_mask
(mask, test)[source]¶ Case insensitive comparison of two strings.
- Parameters
mask (str) – Mask
test (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.
License: Geosoft Open License
Note: Mask characters ‘*’ - matches any one or more up to next character ‘?’ - matches one character
Test is case insensitive
-
classmethod
strins
(dest, ins, orig)[source]¶ This method inserts a string at a specified position.
- Parameters
dest (str_ref) – Destination String
ins (int) – Insert Position
orig (str) – String to add
New in version 5.1.8.
License: Geosoft Open License
Note: If the specified position does not fall within the current string the source string will simply be Concatenated.
-
classmethod
strlen
(str_val)[source]¶ Returns the length of a string.
- Parameters
str_val (str) – String to find the length of
- Returns
String length.
- Return type
int
New in version 5.0.
License: Geosoft Open License
-
classmethod
strncmp
(first, second, n_char, case_sensitive)[source]¶ Compares two strings to a given number of characters.
- Parameters
first (str) – String A
second (str) – String B
n_char (int) – Number of characters to compare
case_sensitive (int) – STR_CASE constants
- Returns
A < B -1 A == B 0 A > B 1
- Return type
int
New in version 5.0.5.
License: Geosoft Open License
-
classmethod
substr
(dest, orig, start, length)[source]¶ Extract part of a string.
- Parameters
dest (str_ref) – Destination string
orig (str) – Origin string
start (int) – Start location
length (int) – Number of characters
New in version 6.2.
License: Geosoft Open License
Note: The destination string length will be less than the requested length if the substring is not fully enclosed in the origin string.
-
classmethod
to_lower
(str_val)[source]¶ Convert a string to lower case.
- Parameters
str_val (str_ref) – String
New in version 5.0.
License: Geosoft Open License
-
classmethod
to_upper
(str_val)[source]¶ Convert a string to upper case.
- Parameters
str_val (str_ref) – String
New in version 5.0.
License: Geosoft Open License
-
classmethod
tokenize
(str_val, soft, hard, esc, quote)[source]¶ Tokenize a string based on any characters.
- Parameters
- Returns
Number of tokens
- Return type
int
New in version 5.0.
License: Geosoft Open License
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
-
classmethod
tokens
(str_val, delims)[source]¶ Tokenize a string
- Parameters
str_val (str_ref) – String to tokenize
delims (str) – Delimiter characters
- Returns
Number of tokens, maximum is 2048
- Return type
int
New in version 5.0.
License: Geosoft Open License
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
get_token
function will not operate correctly in GX.Net code.See also
tokens2
, GetToken_STR
-
classmethod
tokens2
(str_val, soft, hard, esc, quote)[source]¶ General tokenize a string
- Parameters
str_val (str_ref) – String to tokenize
soft (str) – szSoft - Soft delimiters (spaces/tabs)
hard (str) – szHard - Hard delimiters (commas)
esc (str) – szEsc - Escape delimiters (back-slash)
quote (str) – szQuote- Quote delimiters (quote characters)
- Returns
Number of Tokens
- Return type
int
New in version 5.0.
License: Geosoft Open License
Note: This function is for old GX compatibility only. See
tokenize
.DO NOT use this function except in GXC code. The corresponding
get_token
function will not operate correctly in GX.Net code.
-
classmethod
trim_quotes
(str_val)[source]¶ Remove double quotes.
- Parameters
str_val (str_ref) – String to trim
New in version 5.0.
License: Geosoft Open License
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.
-
classmethod
trim_space
(str_val, trim)[source]¶ Remove leading and/or trailing whitespace.
- Parameters
str_val (str_ref) – String to trim
trim (int) – STR_TRIM constants
New in version 5.0.
License: Geosoft Open License
Note: THE STRING IS MODIFIED. Whitespace characters are defined as space, tab, carriage return, new line, vertical tab or formfeed (0x09 to 0x0D, 0x20)
-
classmethod
un_quote
(str_val)[source]¶ Remove double quotes from string
- Parameters
str_val (str_ref) – String to unquote
New in version 5.0.
License: Geosoft Open License
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.
-
classmethod
xyz_line
(line, xyz)[source]¶ Make a valid XYZ line name from a valid
GXDB
line name.- Parameters
line (str) – Line name to convert
xyz (str_ref) – Buffer to hold new line name
New in version 5.0.
License: Geosoft Open License
-
classmethod
FILE_EXT constants¶
Extension option
STR_CASE constants¶
Case sensitivity
STR_ESCAPE constants¶
How to handle escape
STR_FILE_PART constants¶
Parts of a path string
STR_JUSTIFY constants¶
String justification style