Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Macros | Functions | Variables
util.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

#include "ruby/internal/config.h"
#include "ruby/internal/attr/noalias.h"
#include "ruby/internal/attr/nodiscard.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/restrict.h"
#include "ruby/internal/attr/returns_nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/defines.h"
Include dependency graph for util.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define DECIMAL_SIZE_OF_BITS(n)   (((n) * 3010 + 9998) / 9999)
 an approximation of ceil(n * log10(2)), up to 1,048,576 (1<<20) without overflow within 32-bit calculation More...
 
#define DECIMAL_SIZE_OF_BYTES(n)   DECIMAL_SIZE_OF_BITS((n) * CHAR_BIT)
 an approximation of decimal representation size for n-bytes More...
 
#define DECIMAL_SIZE_OF(expr)   DECIMAL_SIZE_OF_BYTES(sizeof(expr))
 An approximation of decimal representation size. More...
 
#define scan_oct(s, l, e)   ((int)ruby_scan_oct((s),(l),(e)))
 Old name of ruby_scan_oct. More...
 
#define scan_hex(s, l, e)   ((int)ruby_scan_hex((s),(l),(e)))
 Old name of ruby_scan_hex. More...
 
#define strdup(s)   ruby_strdup(s)
 Just another name of ruby_strdup. More...
 
#define strtod(s, e)   ruby_strtod((s),(e))
 Just another name of ruby_strtod. More...
 

Functions

unsigned long ruby_scan_digits (const char *str, ssize_t len, int base, size_t *retlen, int *overflow)
 Scans the passed string, assuming the string is a textual representation of an integer. More...
 
unsigned long ruby_scan_oct (const char *str, size_t len, size_t *consumed)
 Interprets the passed string as an octal unsigned integer. More...
 
unsigned long ruby_scan_hex (const char *str, size_t len, size_t *ret)
 Interprets the passed string a hexadecimal unsigned integer. More...
 
void ruby_qsort (void *, const size_t, const size_t, int(*)(const void *, const void *, void *), void *)
 Reentrant implementation of quick sort. More...
 
void ruby_setenv (const char *key, const char *val)
 Sets an environment variable. More...
 
void ruby_unsetenv (const char *key)
 Deletes the passed environment variable, if any. More...
 
char * ruby_strdup (const char *str)
 This is our own version of strdup(3) that uses ruby_xmalloc() instead of system malloc (benefits our GC). More...
 
char * ruby_getcwd (void)
 This is our own version of getcwd(3) that uses ruby_xmalloc() instead of system malloc (benefits our GC). More...
 
double ruby_strtod (const char *str, char **endptr)
 Our own locale-insensitive version of strtod(3). More...
 
void ruby_each_words (const char *str, void(*func)(const char *word, int len, void *argv), void *argv)
 Scans the passed string, with calling the callback function every time it encounters a "word". More...
 

Variables

const signed char ruby_digit36_to_number_table []
 Character to number mapping like ‘'a’->10,'b'->11` etc. More...
 
const char ruby_hexdigits []
 Characters that Ruby accepts as hexadecimal digits. More...
 

Detailed Description

Author
$Author$
Date
Thu Mar 9 11:55:53 JST 1995
Warning
DO NOT ADD RANDOM GARBAGES IN THIS FILE! Contents of this file reside here for historical reasons. Find a right place for your API!

Definition in file util.h.

Macro Definition Documentation

◆ DECIMAL_SIZE_OF

#define DECIMAL_SIZE_OF (   expr)    DECIMAL_SIZE_OF_BYTES(sizeof(expr))

An approximation of decimal representation size.

expr may be a type name

Definition at line 48 of file util.h.

◆ DECIMAL_SIZE_OF_BITS

#define DECIMAL_SIZE_OF_BITS (   n)    (((n) * 3010 + 9998) / 9999)

an approximation of ceil(n * log10(2)), up to 1,048,576 (1<<20) without overflow within 32-bit calculation

Definition at line 39 of file util.h.

◆ DECIMAL_SIZE_OF_BYTES

#define DECIMAL_SIZE_OF_BYTES (   n)    DECIMAL_SIZE_OF_BITS((n) * CHAR_BIT)

an approximation of decimal representation size for n-bytes

Definition at line 42 of file util.h.

◆ strdup

#define strdup (   s)    ruby_strdup(s)

Just another name of ruby_strdup.

Definition at line 187 of file util.h.

◆ strtod

#define strtod (   s,
 
)    ruby_strtod((s),(e))

Just another name of ruby_strtod.

Definition at line 223 of file util.h.

Function Documentation

◆ ruby_each_words()

void ruby_each_words ( const char *  str,
void(*)(const char *word, int len, void *argv)  func,
void *  argv 
)

Scans the passed string, with calling the callback function every time it encounters a "word".

A word here is a series of characters separated by either a space (of IEEE 1003.1 section 7.3.1.1), or a ‘’,'`.

Parameters
[in]strTarget string to split into each words.
[in]funcCallback function.
[in,out]argvPassed as-is to func.

◆ ruby_getcwd()

char* ruby_getcwd ( void  )

This is our own version of getcwd(3) that uses ruby_xmalloc() instead of system malloc (benefits our GC).

Returns
An allocated C string holding the process working directory.
Note
Return value must be discarded using ruby_xfree().

Definition at line 602 of file util.c.

◆ ruby_qsort()

void ruby_qsort ( void *  ,
const  size_t,
const  size_t,
int(*)(const void *, const void *, void *)  ,
void *   
)

Reentrant implementation of quick sort.

If your system provides something (like C11 qsort_s), this is a thin wrapper of that routine. Otherwise resorts to our own version.

Referenced by rb_ary_sort_bang().

◆ ruby_scan_digits()

unsigned long ruby_scan_digits ( const char *  str,
ssize_t  len,
int  base,
size_t *  retlen,
int *  overflow 
)

Scans the passed string, assuming the string is a textual representation of an integer.

Stops when encountering something non-digit for the passed base.

Note
This does not understand minus sign.
This does not understand e.g. 0x prefix.
It is a failure to pass 0 to base, unlike ruby_strtoul().
Parameters
[in]strTarget string of digits to interpret.
[in]lenNumber of bytes of str, or -1 to detect NUL.
[in]baseBase, 2 to 36 inclusive.
[out]retlenReturn value buffer.
[out]overflowReturn value buffer.
Returns
Interpreted numeric representation of str.
Postcondition
retlen is the number of bytes scanned so far.
overflow is set to true if the string represents something bigger than ULONG_MAX. Something meaningful still returns; which is the designed belabour of C's unsigned arithmetic.

Definition at line 103 of file util.c.

Referenced by ruby_strtoul().

◆ ruby_scan_hex()

unsigned long ruby_scan_hex ( const char *  str,
size_t  len,
size_t *  ret 
)

Interprets the passed string a hexadecimal unsigned integer.

Stops when encounters something not understood.

Parameters
[in]strC string to scan.
[in]lenLength of str.
[out]retReturn value buffer.
Returns
Parsed integer.
Postcondition
ret is the number of characters read.

Definition at line 61 of file util.c.

◆ ruby_scan_oct()

unsigned long ruby_scan_oct ( const char *  str,
size_t  len,
size_t *  consumed 
)

Interprets the passed string as an octal unsigned integer.

Stops when encounters something not understood.

Parameters
[in]strC string to scan.
[in]lenLength of str.
[out]consumedReturn value buffer.
Returns
Parsed integer.
Postcondition
ret is the number of characters read.

Definition at line 43 of file util.c.

◆ ruby_setenv()

void ruby_setenv ( const char *  key,
const char *  val 
)

Sets an environment variable.

In case of POSIX this is a wrapper of setenv(3). But there are systems which lack one. We try hard emulating.

Parameters
[in]keyAn environment variable.
[in]valA value to be associated with key, or 0.
Exceptions
rb_eSystemCallErrorsetenv(3) failed for some reason.
Postcondition
Environment variable key is created if necessary. Its value is updated to be val.

Definition at line 5091 of file hash.c.

Referenced by rb_env_clear(), and ruby_unsetenv().

◆ ruby_strdup()

char* ruby_strdup ( const char *  str)

This is our own version of strdup(3) that uses ruby_xmalloc() instead of system malloc (benefits our GC).

Parameters
[in]strTarget C string to duplicate.
Returns
An allocated C string holding the identical contents.
Note
Return value must be discarded using ruby_xfree().

Definition at line 536 of file util.c.

Referenced by ruby_setenv().

◆ ruby_strtod()

double ruby_strtod ( const char *  str,
char **  endptr 
)

Our own locale-insensitive version of strtod(3).

The conversion is done as if the current locale is set to the "C" locale, no matter actual runtime locale settings.

Parameters
[in]strDecimal or hexadecimal representation of a floating point number.
[out]endptrNULL, or an arbitrary pointer (overwritten on return).
Returns
Converted number.
Postcondition
If endptr is not NULL, it is updated to point the first such byte where conversion failed.
Note
This function sets errno on failure.
  • ERANGE: Converted integer is out of range of double.
See also
William D. Clinger, "How to Read Floating Point Numbers Accurately" in Proc. ACM SIGPLAN '90, pp. 92-101. https://doi.org/10.1145/93542.93557

◆ ruby_unsetenv()

void ruby_unsetenv ( const char *  key)

Deletes the passed environment variable, if any.

Parameters
[in]keyAn environment variable.
Exceptions
rb_eSystemCallErrorunsetenv(3) failed for some reason.
Postcondition
Environment variable key does not exist.

Definition at line 5259 of file hash.c.

Variable Documentation

◆ ruby_digit36_to_number_table

const signed char ruby_digit36_to_number_table[]
extern

Character to number mapping like ‘'a’->10,'b'->11` etc.

For punctuation etc., the value is -1. "36" terminology comes from the fact that this is the table behind str.to_i(36).

Definition at line 81 of file util.c.

Referenced by ruby_scan_digits(), and ruby_scan_hex().

◆ ruby_hexdigits

const char ruby_hexdigits[]
extern

Characters that Ruby accepts as hexadecimal digits.

This is /\h/ expanded into an array.

Definition at line 39 of file util.c.