Ruby: include/ruby/util.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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 65536 at least
#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_BITS

#define DECIMAL_SIZE_OF_BITS | ( |  | n | ) |

Value:
(((n) * 3010 + 9998) / 9999)

an approximation of ceil(n * log10(2)), up to 65536 at least

Definition at line 37 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:538

Just another name of ruby_strdup.

Definition at line 176 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 212 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 596 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 550 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 98 of file util.c.

Referenced by ruby_scan_digits(), and 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] | 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 56 of file util.c.

Referenced by ruby_scan_hex().

## ◆ 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 38 of file util.c.

Referenced by ruby_scan_oct().

## ◆ 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 5189 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 538 of file util.c.

Referenced by ruby_getcwd(), 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

## ◆ 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 5371 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 76 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 34 of file util.c.