hb_S - Petewg/harbour-core GitHub Wiki

hb_ScrMaxCol() ➜ nMaxCol
returns the maximum screen column number. (It's zero origin, which means for a 80 columns screen it shall return 79).
hb_ScrMaxRow() ➜ nMaxRow
returns the maximum screen row number. (It's zero origin, which means for a 25 rows screen it shall return 24).
Main difference of the above two functions compared to traditional MaxRow()/MaxCol(), is that the hb_ScrMaxCol()/hb_ScrMaxRow() shall always return the max Column/Row numbers of the main window of the application (window 0). By contrast, the MaxRow()/MaxCol() return the current window's max Column/Row numbers, i.e. the Columns/Rows of the window where they're called from.
hb_Scroll([<nTop>],[<nLeft>],[<nBottom>],[<nRight>],[<nRows>],[<nCols>],[<cnColor>],[<cFillChar>]) ➜ NIL
scrolls the screen region specified by {nTop, nLeft, nBottom, nRight} coordinates.
nRows and nCols, if defined, specify the number of rows/columns the region will be scrolled and they can be positive or negative to force the scrolling to be up or down and left or right respectively.
cnColor is the color designator and cFillChar is the character used to fill the scrolled region.
All arguments are optional.
hb_Sec(<tTimeStamp>) ➜ nSecond
returns the seconds (ss) "member" of a tTimeStamp. The returned value is a floating point number (ss.mmm) where the integer part is seconds while the decimal (fraction) part of it represents milliseconds.

hb_SecondsCPU( [<n>] ) ➜ nTime
reports how many CPU and/or System seconds have elapsed since the beginning of the program execution. See the table for possible value of <n> and the returned values:

Value of <n>	Returned Value
1	User CPU time of the current process
2	System CPU time on behalf of the current process
3	Sum of (1+2) (default value)
11	Sum of the user CPU time of the current + child process
12	Sum of the system CPU time of the current + child process
13	Sum of (11+12)

hb_SecToT( <nSeconds> ) ➜ tTime
converts <nSeconds> seconds to tTimestamp value.
hb_Serialize(<xValue>, [<lNumSize>], [<cCdpIN>], [<cCdpOUT>]) ➜ cSerialized 💎
converts <xValue> into a sequence of bytes that can be used in various ways, (e.g.: save to disk, transmit across a network et.c.).
<xValue> can be a set of data of different types like an array or object or a complex type like timestamp.
The optional parameters <cCdpIN> and <cCdpOUT>, if defined, are used for code-page translation in serialization and de-serialization operations. By default VM's code-page is used.
Harbour does not allow to serialize codeblocks and serialize objects as arrays.
The serialized data can be rebuilt, later, to its original form using the supplementary function hb_Deserialize() . 👇
hb_Deserialize( <cSerialized>, [<cCdpIN>], [<cCdpOUT>] ) ➜ xValue 💎
reconstructs the <cSerialized> byte sequence, previously created (serialized) by 'hb_Serialize()', and returns the data in their original structure, (f.e. array, timestamp, object etc). The optional parameters <cCdpIN> and <cCdpOUT>, if defined, are used for code-page translation in serialization and de-serialization operations. By default VM's code-page is used.
hb_SetClsHandle(<oObject>, <nClassHandle>) ➜ nPrevClassHandle
“Real dirty function, though very usefull under certain circunstances: It allows to change the class handle of an object into another class handle, so the object behaves like a different Class of object. Based on objects.lib SetClsHandle().”
Note: renamed to __objSetClassHandle() while the hb_setClsHandle() old function name covered by HB_LEGACY_LEVEL5 macro (it means, both names co-exists so long as the LEVEL5 is not enabled).
hb_SetCodepage( [<cCodepageID>] ) ➜ cOldCodepageID
❌ depreciated! (in fact, it's been covered by HB_LEGACY_LEVEL2 which means that ~~will be~~ has been removed from newer (i.e. current) builds).
NOTE to users: use hb_cdpSelect() or Set( _SET_CODEPAGE ) instead of this function.
hb_setEnv( <cEnvName>, [<cNewVal>]) ➜ lOK
sets or deletes (when <cNewVal> is NIL) process environment variable <cEnvName>.

hb_SetKeyCP(<cTermCP> [, <cHostCP>])
set automatic input (keyboard) character translation. (see params description below).
hb_SetDispCP(<cTermCP> [, <cHostCP>] [,<lBoxChar>])
set automatic output (screen) character translation.(see params description below).
hb_SetTermCP(<cTermCP> [, <cHostCP>] [,<lBoxChar>])
Sets terminal code-page and enables automatic translation between <cHostCP> (HVM CDP) and <cTermCP> in both, input (keyboard) and output (screen) operations.

PARAMS of the above-mentioned:point_up: three hb_Set...CP() family functions:
- <cTermCP> is the encoding used on external (terminal) side.
- <cHostCP> is the encoding used internally; if not given, then the current code page is used. Some of GTs which uses unicode output may ignore <cTermCP>.
- <lBoxChar> is an optional parameter which interacts with dispbox() output disabling switching to alternate character set in some GTs. It effectively causes that if internal (host) code page contains some letters on the box char positions then they will be shown also by box drawing functions like DispBox() instead of CP437 characters. In some cases it could be useful. By default <lBoxChar> is not set and GTs which can switch between standard and alternate character set (GTCRS, GTSLN) will try to use alternate character set for box drawing functions.
  If <lBoxChar> is .T. then it forces using national letters also in box drawing, thereby disabling CP437 box characters in DispBox() and related functions.

hb_SHA1(<cBuffer> [, <lBin>]) ➜ cDigest
hb_SHA224(<cBuffer> [, <lBin>]) ➜ cDigest
hb_SHA256(<cBuffer> [, <lBin>]) ➜ cDigest
hb_SHA384(<cBuffer> [, <lBin>]) ➜ cDigest
hb_SHA512(<cBuffer> [, <lBin>]) ➜ cDigest
Above functions are used to calculate hash value (digest) of given <cBuffer> according to SHA-1, SHA-2, SHA-3 Secure Hash Algorithms.
<lBin> flag controls whether to return binary data or hexadecimal string, default .F., that is, return hexadecimal string.

hb_StoD( [ <cDate> ] ) ➜ dDate
converts a string representing a date with the format YYYYMMDD to a date value. If no <cDate> is supplied, an empty date string will be returned. (counterpart of the standard DtoS() function).
hb_StoT( <cDateTime> ) ➜ tTimeStamp
converts a datetime string to timestamp value (T).
hb_StrCDecode( <cStr> [, @<lCont> ] ) ➜ cDecodedString | NIL
decodes a string using C compiler rules.
If second parameter <lCont> is passed by reference then it allows to decode multiline strings. In such case, if string ends with unclosed "" quoting then <lCont>is set to .T., so a next call to this function with <lCont> parameter continues string decoding.
The function returns decoded string or NIL on syntax error.
hb_StrClear( @<cVar> ) ➜ lResult
safely erases the content of a string variable, replacing every byte of it with Chr(0).
hb_StrDecodEscape( <cEscSeqStr> ) ➜ cDecodedString
decodes a string containing \ escape sequences.

hb_StrFormat( <%cFormat1...%cFormatX>, <nParam1, ..., nParamN> ) ➜ cString
returns a string with the values of the nParam1, ..., nParamN embedded and formatted according to <%cFormat1...%cFormatX> format specifiers. It is like the printf() function in C-language, but stripped down to fit the Harbour data types; currently the format specifiers that are recognized/processed are: %d, %f, %x, %X, %s and %c.

Specifier	Parameter type/value description
`d`	integer as a signed decimal number
`f`	non integer (float) decimal number in normal fixed-point notation.
`x`, `X`	unsigned integer as a hexadecimal number. `x` uses lower-case letters and `X` uses upper-case.
`s`	string
`c`	ASCII code (numeric) of single character

example usage:

cStr := hb_StrFormat( "- an integer:\t %d\n- a float:\t %3.5f\n- a hex:\t %x\n- a HEX:\t %X\n" + ;
                      "- a string:\t %s \n- a character:\t %c", ;
                      12345, 42.421, 65535, 65535, "Hello harbour!", 122 )
? hb_StrDecodEscape( cStr )

hb_StrIsUTF8( <cString> ) ➜ .T|.F.
returns .T. (true), if <cString> string is UTF-8 encoded. If <cString> is either not UTF-8 encoded or a NULL (empty) string, the function returns .F. (false)!
hb_StrReplace( <cString>, [<cSource>|<acSource>|<hReplace>], [<cDest>|<acDest>] ) ➜ cResult
replaces different sub-strings (characters) in the given <cString>.
- If 2nd parameter is a string then each character in <cString> which exists in <cSource> at <n> position is replaced by corresponding character at <n> position in <cDest> or string from <acDest>[<n>].
- If 2nd parameter is an array then each <cString> sub-string which exists in <acSource> at <n> position is replaced by corresponding character at <n> position in <cDest> or string from <acDest>[<n>]. If <n> is longer then LEN() of <cDest> or <acDest> then given character/sub-string is removed from result.
- If 2nd parameter is a hash table (and 3rd parameter is omitted or is NIL) then each sub-string into <cString> matching a hash key it's replaced by key-value.
  Any not matching or non-character key is ignored while a matching key but with improper value (i.e. not character type value) removes the matched sub-string.
Example:
```
cString := "abcdefghijklmnopqrstuvwxyz0"
? hb_StrReplace( cString, { 'a' => 'A', 'b' => 2, ;
                            32 => 'X', '0' => '42', ;
                            'f' => 'F', 'm' => 'M', ;
                            'z' => '', 'qr' => '<qrKEYVAL>', ;
                            'ab' => '<abVALUE>' } ) 
// result --> `AcdeFghijklMnop<qrKEYVAL>stuvwxy42`
```
In above code:
- the 'b' => 2 pair has a numeric value hence the matched 'b' in cString, (being of different type (char)), is removed.
- the 32 => 'X' pair is ignored (32 is not a character key) .
- the 'ab' => '<abVALUE>' pair fails to have a match, (unlike the 'qr' => '<qrKEYVAL>', which indeed does), although initially the string includes an 'ab', because the 'a' has already become 'A' and the 'b' has already been removed. Worth to note that the case would be totally different had the 'ab' => '<abVALUE>' been the first pair into the hash table!
- all the other are more-or-less self-explanatory...
More Examples:
```
cData := hb_StrReplace( cSource, { "{LI}" => cLIValue, "{FI}" => cFIValue } )
// encode XML value
cXmlText := hb_StrReplace( cText, "<>&", { "&lt;", "&gt;", "&amp;" } )
// now decode it to raw text
cText := hb_StrReplace( cXmlText, { "&lt;", "&gt;", "&amp;" }, "<>&" )
// strip all digits from string
cNoDigit := hb_StrReplace( cText, "0123456789" )
// extract all digits from string
cDigits := hb_StrReplace( cText, cNoDigit )
// convert chosen letters to upper case
? hb_StrReplace( "hello world, "hlwd", "HLWD" )
```
See also: StrTran()
Read also: https://groups.google.com/forum/#!msg/harbour-devel/vSzlAkv6h9Y/jkOJhWyDeVEJ
hb_StrShrink( <cString> [, <nCount>] ) ➜ cNewString
Shrinks the string <cString>, by «eating» (removing) from right side of the string the number of characters specified by <nCount>.
It's similar to Left( cString, Len( cString ) - nCount ) but simpler and faster.
If optional parameter <nCount> is omitted, it defaults to 1. If <nCount> is equal to or greater than Len(<cString>) then a null string is returned.
hb_StrToExp( <cString> [, <lEscaped>] ) ➜ cExpression
converts string item to valid expression which can be compiled by macro compiler. String may contain any characters. However, if <lEscaped> passed as .T., the string returned will be prefixed by the escape literal 'e' (e.g.: e"String").
hb_StrToHex( <cString> [, <cSeparator> ] ) ➜ cHexValues
converts a string (or buffer) into a string of it's corresponding hexadecimal values optionally separated by <cSeparator>. f.e.: hb_StrToHex( "harbour", ":" ) => "68:61:72:62:6F:75:72" or => "686172626F7572" when no ":" separator given.
hb_StrToTS( <cTimeStamp> ) ➜ tTimeStamp
converts a string cTimeStamp to tTimeStamp timestamp value. The <cTimeStamp> must have the format: YYYY-MM-DD [H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM] or YYYY-MM-DDT[H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM]. See also the inverse 'hb_TSToStr()' function.
hb_strToUTF8(<cStr> [,<cCPID>]) ➜ cUTF8Str
converts ("translates") a given string to UTF-8 format. It is similar to 'hb_Translate(cStr, cFromCPID, cToCPID', yet dedicated to convert strings exclusively to UTF-8 encoding.
<cCPID> is the Harbour code-page id, (f.e.: "EN", "ES", "ESWIN") in which the string <cStr> is currently encoded, and will be used as basis for the conversion. If no <cCPID> is given, then the default HVM code-page or the one set by hb_cdpSelect() function is used.
See also, hb_Translate().
hb_StrXor( <cString>, <cnBytes> ) ➜ cResult
Performs a XOR operation in each character of <cString> with the string or number supplied in <cnBytes>.
HB_SYMBOL_UNUSED( <symbol> ) ➜ Nothing!
Pseudo-function (macro) that can be used to suppress unused var warnings where applicable (such warnings raised by -w2 & -w3 compiler switches). The code won't generate any final pcodes, so it won't cause overhead and, of course, it does return nothing!

NOTE: there exist (in harbour-core library) a hb_socket* family of functions. See Harbour Socket API

🔙 Home

hb_S - Petewg/harbour-core GitHub Wiki

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️