Ruby: include/ruby/util.h File Reference

Ruby 3.4.1p0 (2024-12-25 revision 48d4efcb85000e1ebae42004e963b5d0cedddcf2)

Macros | Functions | Variables
util.h File Reference
`#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"`

Go to the source code of this file.

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

## 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.
unsigned long | ruby_scan_oct (const char *str, size_t len, size_t *consumed)
| Interprets the passed string as an octal unsigned integer.
unsigned long | ruby_scan_hex (const char *str, size_t len, size_t *ret)
| Interprets the passed string a hexadecimal unsigned integer.
void | ruby_qsort (void *, const size_t, const size_t, int(*)(const void *, const void *, void *), void *)
| Reentrant implementation of quick sort.
void | ruby_setenv (const char *key, const char *val)
| Sets an environment variable.
void | ruby_unsetenv (const char *key)
| Deletes the passed environment variable, if any.
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).
char * | ruby_getcwd (void)
| This is our own version of `getcwd(3)` that uses ruby_xmalloc() instead of system malloc (benefits our GC).
double | ruby_strtod (const char *str, char **endptr)
| Our own locale-insensitive version of `strtod(3)`.
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".

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

## Detailed Description

Author
  $Author$

Date
  Thu Mar 9 11:55:53 JST 1995

Copyright
  Copyright (C) 1993-2007 Yukihiro Matsumoto
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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 | ) |

Value:
DECIMAL_SIZE_OF_BYTES(sizeof(expr))
DECIMAL_SIZE_OF_BYTES
#define DECIMAL_SIZE_OF_BYTES(n)
an approximation of decimal representation size for n-bytes
Definition util.h:42

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 | ) |

Value:
(((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 | ) |

Value:
DECIMAL_SIZE_OF_BITS((n) * CHAR_BIT)
DECIMAL_SIZE_OF_BITS
#define DECIMAL_SIZE_OF_BITS(n)
an approximation of ceil(n * log10(2)), up to 1,048,576 (1<<20) without overflow within 32-bit calcul...
Definition util.h:39

an approximation of decimal representation size for n-bytes

Definition at line 42 of file util.h.

## ◆ strdup

#define strdup | ( |  | s | ) |

Value:
ruby_strdup(s)
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 ...
Definition util.c:536

Just another name of ruby_strdup.

Definition at line 187 of file util.h.

## ◆ strtod

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

Value:
ruby_strtod((s),(e))
ruby_strtod
double ruby_strtod(const char *str, char **endptr)
Our own locale-insensitive version of strtod(3).

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(* | 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".

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] | str | Target string to split into each words.
  [in] | func | Callback function.
  [in,out] | argv | Passed as-is to `func`.

Definition at line 617 of file util.c.

Referenced by ruby_each_words().

## ◆ 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.

Referenced by ruby_getcwd().

## ◆ 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] | str | Target string of digits to interpret.
  [in] | len | Number of bytes of `str`, or -1 to detect `NUL`.
  [in] | base | Base, `2` to `36` inclusive.
  [out] | retlen | Return value buffer.
  [out] | overflow | Return 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.

## ◆ 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] | str | C string to scan.
  [in] | len | Length of `str`.
  [out] | ret | Return 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] | str | C string to scan.
  [in] | len | Length of `str`.
  [out] | consumed | Return 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] | key | An environment variable.
  [in] | val | A value to be associated with `key`, or 0.

Exceptions

  rb_eSystemCallError | `setenv(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.

## ◆ 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] | str | Target 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_qsort(), ruby_setenv(), and ruby_strdup().

## ◆ 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] | str | Decimal or hexadecimal representation of a floating point number.
  [out] | endptr | NULL, 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

Referenced by ruby_strtod().

## ◆ ruby_unsetenv()

void ruby_unsetenv | ( | const char * | key | ) |

Deletes the passed environment variable, if any.

Parameters

  [in] | key | An environment variable.

Exceptions

  rb_eSystemCallError | `unsetenv(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 behindstr.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.