(cb302881629f997f403e705425f69e5f6b0741ac)

#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

#define	DECIMAL_SIZE_OF_BYTES(n) DECIMAL_SIZE_OF_BITS((n) * CHAR_BIT)
	an approximation of decimal representation size for n-bytes

#define	DECIMAL_SIZE_OF(expr) DECIMAL_SIZE_OF_BYTES(sizeof(expr))
	An approximation of decimal representation size.

#define	scan_oct(s, l, e) ((int)ruby_scan_oct((s),(l),(e)))
	Old name of ruby_scan_oct.

#define	scan_hex(s, l, e) ((int)ruby_scan_hex((s),(l),(e)))
	Old name of ruby_scan_hex.

#define	strdup(s) ruby_strdup(s)
	Just another name of ruby_strdup.

#define	strtod(s, e) ruby_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 ) 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,
		e
	)	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]	str	Target string to split into each words.
[in]	func	Callback function.
[in,out]	argv	Passed 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 581 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.

◆ 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 82 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 52 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 5446 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 515 of file util.c.

Referenced by 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 5600 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'->11etc.

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 60 of file util.c.

Referenced by ruby_scan_digits().

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

(cb302881629f997f403e705425f69e5f6b0741ac)

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DECIMAL_SIZE_OF

◆ DECIMAL_SIZE_OF_BITS

◆ DECIMAL_SIZE_OF_BYTES

◆ strdup

◆ strtod

Function Documentation

◆ ruby_each_words()

◆ ruby_getcwd()

◆ ruby_qsort()

◆ ruby_scan_digits()

◆ ruby_scan_hex()

◆ ruby_scan_oct()

◆ ruby_setenv()

◆ ruby_strdup()

◆ ruby_strtod()

◆ ruby_unsetenv()

Variable Documentation

◆ ruby_digit36_to_number_table

◆ ruby_hexdigits